Documentation

Add documentation for:
    bash cli
    install_hotwater
    uninstall_hotwater
    run
    Add package description

Changes
    remove remotes and xml2 from suggests (not needed)
    don't use localhost for pinging
    fix lintr typo

.lintr

@@ -3,7 +3,7 @@ linters: linters_with_defaults(
   implicit_integer_linter(),
   indentation_linter(indent = 4L),
   object_name_linter(styles = c("snake_case", "symbols"), regexes = character()),
-  object_name_linter = NULL
+  object_usage_linter = NULL
   )
 exclusions: list("man/", "inst/", "src/", ".vscode/", ".Rproj.user/", "R/import-standalone-obj-type.R", "R/import-standalone-types-check.R")
 encoding: "UTF-8"

DESCRIPTION

@@ -1,10 +1,10 @@
 Package: hotwater
-Title: autoreload plumber APIs
+Title: Live Reload for Plumber APIs
 Version: 0.0.0.9002
 Authors@R:
     person("Elian", "Thiele-Evans", , "[email protected]", role = c("aut", "cre"),
            comment = c(ORCID = "0000-0001-8008-3165"))
-Description: What the package does (one paragraph).
+Description: Enhances development for plumber APIs by enabling live reloading. Monitors API files for changes and automatically refreshes the server and connected web clients, allowing for faster API iteration.
 License: GPL (>= 3)
 URL: https://github.com/ElianHugh/hotwater
 BugReports: https://github.com/ElianHugh/hotwater/issues
@@ -19,9 +19,7 @@ Imports:
 Suggests:
     box,
     docopt,
-    remotes,
     testthat (>= 3.0.0),
-    xml2,
     withr
 Config/testthat/edition: 3
 Encoding: UTF-8

R/middleware.R

@@ -50,7 +50,11 @@ publish_browser_reload <- function(engine) {
 is_plumber_running <- function(engine) {
     tryCatch(
         expr = {
-            url <- sprintf("localhost:%s/__hotwater__", engine$config$port)
+            url <- sprintf(
+                "%s:%s/__hotwater__",
+                engine$config$host,
+                engine$config$port
+            )
             res <- httr2::request(url) |>
                 httr2::req_perform() |>
                 httr2::resp_status()

R/run.R

@@ -1,25 +1,57 @@
-#' Start hotwater engine
+#' Start a hotwater engine
 #'
 #' @description
-#' Start a hotwater engine, which launches a plumber API that is restarted whenever
-#' the plumber API's folder is modified.
 #'
-#' Extra directories can be specified to refresh the API when directories other than the plumber folder are modified.
+#' Start the hotwater engine, launching a plumber API
+#' that is restarted whenever a file in the plumber API's folder is modified.
 #'
-#' If a plumber endpoint returns an html response, when hotwater refreshes the API, hotwater will also order
-#' a refresh of any webpage that is using the API.
+#' Extra directories can be specified to refresh the API when
+#' directories other than the plumber folder are modified.
 #'
-#' @param path path to plumber file
-#' @param dirs extra directories to watch
-#' @param port port to launch API on, defaults to `httpuv::randomPort()`
-#' @param host host to launch API on, defaults to "127.0.0.1"
-#' @param ignore vector of files or file extensions to ignore (globs)
+#' If a plumber endpoint returns an HTML response, when hotwater
+#' refreshes the API, \{hotwater\} will also order a refresh of any
+#' webpage that is using the API.
+#'
+#' @details
+#'
+#' To refresh the browser, a postserialize [plumber::pr_hook] is used to
+#' inject a websocket into the HTML client that listens for the
+#' plumber server refresh.
+#'
+#' @param path path to plumber API file.
+#'
+#' @param dirs (optional) a character vector of extra directories
+#' to watch for file changes. Paths are resolved from the current working
+#' directory, not the directory of the plumber API file.
+#'
+#' @param port \[default [httpuv::randomPort()]] port to launch API on.
+#'
+#' port can either be set explicitly, or it defaults to the
+#' `plumber.port` option. If the plumber option is undefined, the fallback
+#' value of [httpuv::randomPort()] is used.
+#'
+#' @param host \[default "127.0.0.1"] host to launch API on.
+#'
+#' host can either be set explicitly, or it defaults to the
+#' `plumber.host` option. If the plumber option is undefined, the fallback
+#' value of "127.0.0.1" is used.
+#'
+#' @param ignore \[default `c("*.sqlite", "*.git*")`] vector of file globs
+#' to ignore.
+#'
+#' @seealso [plumber::options_plumber],
+#' [plumber::get_option_or_env], [plumber::serializer_html]
 #'
 #' @examples
 #' if (interactive()) {
-#'  hotwater::run(system.file("examples", "plumber.R", package = "hotwater"))
+#'  # start a hotwater session on port 9999
+#'  hotwater::run(
+#'    path = system.file("examples", "plumber.R", package = "hotwater"),
+#'    port = 9999L
+#'  )
 #' }
 #'
+#' @return NULL
 #' @export
 run <- function(path, dirs = NULL, port = NULL, host = NULL, ignore = NULL) {
     config <- new_config(

R/script.R

@@ -1,3 +1,27 @@
+#' @title Run hotwater from the command line
+#'
+#' @description
+#' Following [hotwater::install_hotwater()], the `hotwater` command can be used
+#' to run a hotwater engine straight from the terminal. See
+#' [hotwater::run()] for further details on default values.
+#'
+#' `hotwater -v` will provide the current version of hotwater.
+#' `hotwater -h` will provide help text.
+#'
+#' @param -f plumber file
+#' @param -d extra directories
+#' @param -p plumber port
+#' @param -h show help
+#' @param --host plumber host
+#' @seealso [hotwater::run()]
+#' @examples
+#' # ```sh
+#' # hotwater -f path/to/app.R -p 9999
+#' # ```
+#' @rdname cli
+#' @name cli
+NULL
+
 common_install_paths <- list(
     unix = c(
         "~/.local/bin/",
@@ -9,8 +33,21 @@ common_install_paths <- list(
     windows = c() # does windows even work with this?
 )
 
-#' WORK IN PROGRESS
-#' @param install_folder folder (in PATH) to install hotwater
+#' Install global hotwater script
+#'
+#' If hotwater is installed, users may run `hotwater` from the command line
+#' rather than from an R terminal.
+#'
+#' @param install_folder \[default "~/.local/bin/"] folder to install hotwater
+#' script into. To run as expected, make sure that the folder supplied is on your
+#' `PATH` envar.
+#' @seealso [hotwater::uninstall_hotwater]
+#' @examples
+#' if (interactive()) {
+#'  hotwater::install_hotwater()
+#' }
+#' @return NULL
+#'
 #' @export
 install_hotwater <- function(install_folder = "~/.local/bin/") {
     p <- file.path(install_folder, "hotwater")
@@ -31,8 +68,16 @@ install_hotwater <- function(install_folder = "~/.local/bin/") {
     }
 }
 
-#' WORK IN PROGRESS
-#' @param install_folder folder (in PATH) to uninstall hotwater
+#' Uninstall global hotwater script
+#'
+#' @param install_folder \[default "~/.local/bin/"] folder to uninstall hotwater
+#' from.
+#' @examples
+#' if (interactive()) {
+#'     hotwater::uninstall_hotwater()
+#' }
+#' @seealso [hotwater::install_hotwater]
+#' @return NULL
 #' @export
 uninstall_hotwater <- function(install_folder = "~/.local/bin/") {
     p <- file.path(install_folder, "hotwater")
@@ -50,7 +95,7 @@ uninstall_hotwater <- function(install_folder = "~/.local/bin/") {
 
 #' Check suggested packages for CLI usage
 #'
-#' The {docopt} and {remotes} packages are required to run hotwater from the command line.
+#' The {docopt} package is required to run hotwater from the command line.
 #'
 #' @noRd
 check_suggests <- function() {
@@ -68,13 +113,11 @@ check_suggests <- function() {
     }
 }
 
-#' Run hotwater as a bash script
-#' @noRd
 run_cli <- function() {
     doc <- "hotwater
 
     Usage:
-        hotwater --file=FILE [--dirs=DIRS] [--port=PORT] [--host=SERVER]
+        hotwater --file=FILE [--dirs=DIRS] [--port=PORT] [--host=HOST]
         hotwater -h | --help
         hotwater -v | --version
 
@@ -84,7 +127,7 @@ run_cli <- function() {
         -f FILE --file=FILE         plumber path (required)
         -d DIRS --dirs=DIRS         extra directories
         -p PORT --port=PORT         plumber port
-        -s SERVER --server=SERVER   plumber host
+        --host=HOST                 plumber host
     "
 
     args <- docopt::docopt(
@@ -96,6 +139,6 @@ run_cli <- function() {
         path = args$file,
         dirs = args$dirs,
         port = if (is.null(args$port)) NULL else as.numeric(args$port),
-        host = args$server
+        host = args$host
     )
 }

R/utils.R

@@ -4,6 +4,6 @@
     if (is.null(x)) y else x
 }
 
-`%|NA|%` <- function(x, y) {
+`%|NA|%` <- function(x, y) { # nolint: object_name_linter.
     if (is.na(x)) y else x
-}
+}

README.md

@@ -1,18 +1,18 @@
 <!-- @format -->
 
-# hotwater
+# 🌡️💧 hotwater
 
 <!-- badges: start -->
 
 [![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental)
+[![hotwater status badge](https://elianhugh.r-universe.dev/badges/hotwater)](https://elianhugh.r-universe.dev/hotwater)
 [![Codecov test coverage](https://codecov.io/gh/ElianHugh/hotwater/branch/main/graph/badge.svg)](https://app.codecov.io/gh/ElianHugh/hotwater?branch=main)
 [![R-CMD-check](https://github.com/ElianHugh/hotwater/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/ElianHugh/hotwater/actions/workflows/R-CMD-check.yaml)
 
 <!-- badges: end -->
 
-- for plumber development
 - autoreload for plumber
-- also auto-refreshes the browser when a change is made
+- auto-refresh the browser when a change is made
 - run from the commandline with the `/exec/hotwater` bash script
 
 ## Installation

exec/hotwater

@@ -2,7 +2,7 @@
 
 if (!requireNamespace("hotwater", quietly = TRUE)) {
     cli::cli_inform("Bootstrapping hotwater...")
-    remotes::install_github("ElianHugh/hotwater")
+    utils::install.packages("hotwater", repos = "https://elianhugh.r-universe.dev")
 }
 
 hotwater:::check_suggests()