Merge pull request #461 from carpentries/add-servr-options

allow serve to modify server settings

NEWS.md

@@ -1,10 +1,20 @@
 # sandpaper 0.11.17 (unreleased)
 
+## NEW FEATURES
+
+* `sandpaper::serve()` gains the `quiet` argument, defaulting to `TRUE` for
+  interactive sessions and `FALSE` for command line sessions 
+* `sandpaper::serve()` gains the `...` argument to pass options to 
+  `servr::server_config()` for setting ports and hosts (reported:
+  @twrightsman, https://github.com/carpentries/workbench/issues/50 and #459;
+  fixed: @zkamvar, #461).
+
 ## BUG FIX
 
 * Break timing is now included in the overall schedule. (reported: @karenword,
   #437; fixed: @bencomp, #455).
 
+
 ## TEST SUITE
 
 * An upstream feature in {renv}, forcing it to be silent when testing caused

R/serve.R

@@ -4,19 +4,43 @@
 #' save a file.
 #'
 #' @param path the path to your lesson. Defaults to the current path.
-#' @return the output of `servr::httw()`, invisibly. This is mainly used for its
+#' @param quiet if `TRUE`, then no messages are printed to the output. Defaults
+#'   to `FALSE` in non-interactive sessions, which allows messages to be
+#'   printed.
+#' @param ... options passed on to [servr::server_config()] by way of
+#'   [servr::httw()]. These can include **port** and **host** configuration.
+#' @return the output of [servr::httw()], invisibly. This is mainly used for its
 #'   side-effect
 #'
-#'
 #' @details
 #' `sandpaper::serve()` is an entry point to working on any lesson using The
-#' Carpentries Workbench. When you run this function, a preview window will
-#' open either in RStudio or your browser with an address like `localhost:4213`
-#' (note the number will likely be different). When you make changes to files
-#' in your lesson, this preview will update automatically.
+#' Carpentries Workbench. When you run this function interactively, a preview
+#' window will open either in RStudio or your browser with an address like
+#' `localhost:4321` (note the number will likely be different). When you make
+#' changes to files in your lesson, this preview will update automatically.
 #'
 #' When you are done with the preview, you can run `servr::daemon_stop()`.
 #'
+#' ## Command line usage
+#'
+#' You can use this on the command line if you do not use RStudio or another
+#' IDE that acts as a web browser. To run this on the command line, use:
+#'
+#' ```bash
+#' R -e 'sandpaper::serve()'
+#' ```
+#'
+#' Note that unlike an interactive session, progress messages are not printed
+#' (except for the accessibility checks) and the browser window will not
+#' automatically launch. You can have these messages print to screen with the
+#' `quiet = FALSE` argument. In addition, If you want to specify a port and
+#' host for this function, you can do so using the port and host arguments:
+#'
+#' ```bash
+#' R -e 'sandpaper::serve(quiet = FALSE, host = "127.0.0.1", port = "3435")'
+#' ```
+#'
+#'
 #' @export
 #' @seealso [build_lesson()], render the lesson once, locally.
 #' @examples
@@ -31,15 +55,21 @@
 #'  # serve the lesson and begin editing the file. Watch how the file will
 #'  # auto-update whenever you save it.
 #'  sandpaper::serve()
+#'  #
+#'  # to stop the server, run
+#'  servr::daemon_stop()
+#'  #
+#'  # If you want to use a different port, you can specify it directly
+#'  sandpaper::serve(host = "127.0.0.1", port = "3435")
 #' }
 #nocov start
 # Note: we can not test this in covr because I'm not entirely sure of how to get
 #       it going
-serve <- function(path = ".") {
+serve <- function(path = ".", quiet = !interactive(), ...) {
   this_path <- root_path(path)
   rend <- function(file_list = this_path) {
     for (f in file_list) {
-      build_lesson(f, preview = FALSE)
+      build_lesson(f, preview = FALSE, quiet = quiet)
     }
   }
   # path to the production folder that {servr} needs to render
@@ -62,6 +92,7 @@ serve <- function(path = ".") {
   this_filter <- make_filter(this_path)
   # to start, build the site and then watch things:
   rend(this_path)
-  servr::httw(prod, watch = this_path, filter = this_filter, handler = rend)
+  servr::httw(prod, watch = this_path, filter = this_filter, handler = rend,
+    ...)
 }
 #nocov end