Merge pull request #422 from metrumresearchgroup/docs-update

Expand docs and set up site

.github/workflows/site.yaml

@@ -0,0 +1,67 @@
+name: Deploy site
+on:
+  push:
+    branches:
+      - scratch/deploy-site
+    tags:
+      - 'v[0-9]+.[0-9]+.[0-9]+'
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Install Hugo
+        shell: bash
+        run: |
+          tdir=$(mktemp -d)
+          tgz=$tdir/hugo.tar.gz
+          bin=$HOME/bin
+          mkdir -p "$bin"
+
+          url=https://github.com/gohugoio/hugo/releases/download
+          curl -fSsL --retry 3 \
+            "$url/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz" \
+            >"$tgz"
+          printf '%s  %s\n' "$HUGO_SHA" "$tgz" | sha256sum --check >/dev/null
+
+          tar --to-stdout --extract -zf "$tgz" hugo >"$bin"/hugo
+          chmod +x "$bin/hugo"
+          "$bin"/hugo version
+          echo "$bin" >>"$GITHUB_PATH"
+        env:
+          HUGO_VERSION: '0.133.0'
+          HUGO_SHA: '372530e2de9ae74087a987ca841429390a055123b8a4dec665cc601f10dc8e6e'
+      - uses: actions/configure-pages@v5
+        id: pages
+      - name: Check URL match
+        shell: bash
+        run: |
+          url=$(grep '^baseURL:' docs/site/hugo.yaml)
+          test "${{ steps.pages.outputs.base_url }}/" = "${url#baseURL: }"
+      - name: Build site
+        shell: bash
+        run: make -C docs/site build
+        env:
+          HUGO_ENVIRONMENT: production
+          HUGO_CACHEDIR: ${{ runner.temp }}/hugo_cache
+          TZ: America/New_York
+      - name: Upload site
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./docs/site/public
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

README.md

@@ -1,16 +1,17 @@
 # pkgr
 
-For additional details of how to use pkgr, please see the [user manual](https://github.com/metrumresearchgroup/pkgr/wiki/user_manual)
+Documentation for `pkgr` is available at
+<https://metrumresearchgroup.github.io/pkgr/docs/>.
 
-# What is pkgr?
+## What is pkgr?
 
 `pkgr` is a rethinking of the way packages are managed in R. Namely, it embraces
 the declarative philosophy of defining _ideal state_ of the entire system, and working
 towards achieving that objective. Furthermore, `pkgr` is built with a focus on reproducibility
 and auditability of what is going on, a vital component for the pharmaceutical sciences + enterprises.
 
 
-# Why pkgr?
+## Why pkgr?
 
 `install.packages` and friends such as `remotes::install_github` have a subtle weakness --
 they are not good at controlling desired global state. There are some knobs that
@@ -31,14 +32,14 @@ the same set of responsibilities (dealing with dataframes + dealing with other l
 As such, it is becoming increasingly difficult to manage the _set_ of packages in a transparent and robust
 way.
 
-### how does it compare with pak can be read about [here](https://github.com/metrumresearchgroup/pkgr/issues/222#issuecomment-576340217)
-
+> [!NOTE]
+> How pkgr compares with pak can be read about [here](https://github.com/metrumresearchgroup/pkgr/issues/222#issuecomment-576340217).
 
 ## pkgr in action
 
 [![asciicast](https://asciinema.org/a/wgcPBvCMtEwhpdW793MBjgSi2.svg)](https://asciinema.org/a/wgcPBvCMtEwhpdW793MBjgSi2)
 
-# Getting Started
+## Getting Started
 
 ### OSX and Linux installation
 
@@ -56,13 +57,17 @@ Pkgr for Windows is supported, but we have not yet published on a Windows-compat
   - The destination folder should be on your Windows PATH. You may need to [modify your Windows PATH environment variable](https://www.architectryan.com/2018/03/17/add-to-the-path-on-windows-10/) to make this happen.
   - If you do not already have a preferred way of accomplishing the above, we suggest creating a folder called "apps" in your home directory, then adding the "apps" directory to your PATH. From there, simply make sure that the `pkgr.exe` file from the tarball ends up in your "apps/" directory.
 
-# How it works
+## How it works
+
+> [!NOTE]
+> For additional details of how to use pkgr, please see the
+> [user manual](https://github.com/metrumresearchgroup/pkgr/wiki/user_manual).
 
 `pkgr` is a command line utility with several top level commands. The two primary commands are:
 
 ```bash
 pkgr plan # show what would happen if install is run
-pkgr install # install the packages specified in pkgr.config
+pkgr install # install the packages specified in pkgr.yml
 ```
 The actions are controlled by a configuration file that specifies the desired global state, namely,
 by defining the top level packages a user cares about, as well as specific configuration customizations.
@@ -184,7 +189,7 @@ Logging:
   overwrite: true
 ```
 
-# pkgr and [packrat](https://rstudio.github.io/packrat/) and renv
+## pkgr and [packrat](https://rstudio.github.io/packrat/) and renv
 
 **Pkgr is not a replacement for Packrat/renv -- Pkgr is complementary to packrat/renv**.
 
@@ -207,3 +212,23 @@ Pkgr solves these issues by:
   - Providing timely error messages and halting the installation process immediately when something goes wrong during the
   installation process (such as a package not being available, a repository being unreachable, etc.)
 
+## Development
+
+To run the test suite, you can invoke [scripts/run-unit-tests][ru] and
+[scripts/run-integration-tests][ri] directly or via `make vt-test`.
+
+After updating a subcommand, regenerate the Markdown documentation at
+[docs/commands][dc] by running `make vt-gen-docs`.  See `make vt-help` and
+[internal/valtools/README.md][vr] for more details on the validation tooling.
+
+The setup for building the documentation site is described in
+[docs/site/README.md][dr].
+
+<!-- Note: Use GitHub URLs rather than relative paths (e.g., "/docs/commands") so -->
+<!-- that these work on https://metrumresearchgroup.github.io/pkgr/ without further -->
+<!-- processing. -->
+[dc]: https://github.com/metrumresearchgroup/pkgr/blob/main/docs/commands
+[dr]: https://github.com/metrumresearchgroup/pkgr/blob/main/docs/site/README.md
+[ri]: https://github.com/metrumresearchgroup/pkgr/blob/main/scripts/run-integration-tests
+[ru]: https://github.com/metrumresearchgroup/pkgr/blob/main/scripts/run-unit-tests
+[vr]: https://github.com/metrumresearchgroup/pkgr/blob/main/internal/valtools/README.md

cmd/add.go

@@ -26,18 +26,22 @@ import (
 
 // installCmd represents the R CMD install command
 var addCmd = &cobra.Command{
-	Use:   "add [package name1] [package name2] [package name3] ...",
-	Short: "add one or more packages",
-	Long: `
-	add package/s to the configuration file and optionally install
-`,
+	Use:   "add [flags] <package> [<package>...]",
+	Short: "Add packages to the configuration file",
+	Long: `Add the specified packages to the 'Packages' section of the
+configuration file.`,
+	Example: `  # Add mrgsolve and bbr to list of packages
+  pkgr add mrgsolve bbr
+  # Add rlang and then do installation
+  # (same result as following up with 'pkgr install' call)
+  pkgr add --install rlang`,
 	RunE: rAdd,
 }
 
 var install bool
 
 func init() {
-	addCmd.Flags().BoolVar(&install, "install", false, "install package/s after adding")
+	addCmd.Flags().BoolVar(&install, "install", false, "run install after updating config")
 	RootCmd.AddCommand(addCmd)
 }
 

cmd/clean.go

@@ -26,10 +26,22 @@ var cleanAll bool
 
 // CleanCmd represents the clean command
 var CleanCmd = &cobra.Command{
-	Use:   "clean",
-	Short: "clean up cached information",
-	Long:  "clean up cached source files and binaries, as well as the saved package database.",
-	RunE:  clean,
+	Use:   `clean [flags]`,
+	Short: "Clean cached information",
+	Long: `This subcommand is an entry point for cleaning two categories of cached
+data:
+
+ * source and binary tarballs
+
+   Use the 'cache' subcommand to remove these.
+
+ * package databases with information about the packages available from
+   repositories
+
+   Use the 'pkgdbs' subcommand to remove these.
+
+To remove cached data for both categories, pass the --all flag.`,
+	RunE: clean,
 }
 
 func init() {

cmd/cleanCache.go

@@ -35,22 +35,27 @@ var reposToClear string
 // cacheCmd represents the cache command
 var cleanCacheCmd = &cobra.Command{
 	Use:   "cache",
-	Short: "Subcommand to clean cached source and binary files.",
-	Long: `This command is a subcommand of the "clean" command.
-
-	Using this command deletes cached source and binary files. Use the
-	--src and --binary options to specify which repos to clean each
-	file type from.
-
-	`,
+	Short: "Clean cached package tarballs",
+	Long: `Delete cached tarballs for source and binary packages. Both source and
+binary files are deleted if neither the --src-only or --binaries-only flags
+is specified.
+
+By default, files for all repositories are deleted unless specific
+repositories are specified via the --repos option. Note that the value must
+match the directory name in the cache, including the unique ID that is
+appended to the repository name.`,
+	Example: `  # Clean binary files for all repos
+  pkgr clean cache --binaries-only
+  # Clean binaries files for MPN-889df4238bae repo
+  pkgr clean cache --repos=MPN-889df4238bae --binaries-only`,
 	RunE: cache,
 }
 
 func init() {
 	//cleanCacheCmd.Flags().BoolVar(&cleanAllFromCache, "all", true, "Clean both src and binary files from the cache.")
-	cleanCacheCmd.Flags().BoolVar(&srcOnly, "src-only", false, "Clean only src files from the cache")
-	cleanCacheCmd.Flags().BoolVar(&binariesOnly, "binaries-only", false, "Clean only binary files from the cache")
-	cleanCacheCmd.Flags().StringVar(&reposToClear, "repos", "ALL", "Comma separated list of repositories to be cleaned. Defaults to all.")
+	cleanCacheCmd.Flags().BoolVar(&srcOnly, "src-only", false, "clean only source files from the cache")
+	cleanCacheCmd.Flags().BoolVar(&binariesOnly, "binaries-only", false, "clean only binary files from the cache")
+	cleanCacheCmd.Flags().StringVar(&reposToClear, "repos", "ALL", "comma-separated list of repositories to be cleaned. Defaults to all.")
 
 	CleanCmd.AddCommand(cleanCacheCmd)
 }

cmd/cleanPkgdb.go

@@ -29,17 +29,19 @@ var pkgdbsToClearArgument string
 // pkgdbCmd represents the pkgdb command
 var pkgdbsCmd = &cobra.Command{
 	Use:   "pkgdbs",
-	Short: "Subcommand to clean cached pkgdbs",
-	Long: `This command parses the currently-cached pkgdbs and removes all
-	of them by default, or specific ones if desired. Identify specific repos using the "repos" argument, i.e.
-	pkgr clean pkgdbs --repos="CRAN,r_validated"
-	Repo names should match names in the pkgr.yml file.`,
+	Short: "Clean cached package databases",
+	Long: `Delete cached package databases. By default, remove cached databases for
+every repository listed in the active configuration file. If the --repos option
+is passed, remove only the cached databases for those repositories. Repo names
+should match the names in the configuration file.`,
+	Example: `  # Clean package databases for CRAN and MPN
+  pkgr clean pkgdbs --repos=CRAN,MPN`,
 	RunE: executeCommand,
 }
 
 func init() {
 
-	pkgdbsCmd.Flags().StringVar(&pkgdbsToClearArgument, "repos", "ALL", "Set the repos you wish to clear the pkgdbs for.")
+	pkgdbsCmd.Flags().StringVar(&pkgdbsToClearArgument, "repos", "ALL", "clear databases for these repos")
 	CleanCmd.AddCommand(pkgdbsCmd)
 }
 

cmd/inspect.go

@@ -29,11 +29,30 @@ import (
 
 // inspectCmd shows the install inspect
 var inspectCmd = &cobra.Command{
-	Use:   "inspect",
-	Short: "inspect a full installation",
-	Long: `
-	see the inspect for an install
- `,
+	Use:   "inspect --deps [flags] [<package>...]",
+	Short: "Inspect package dependencies",
+	Long: `The inspect subcommand provides an entry point for displaying
+information that can be gathered by examining the configuration file, the
+associated package database, and the library. The current focus is on
+inspecting package dependencies (triggered by passing --deps).
+
+Note: If the configuration file has 'Suggests: true', that does not affect
+the set of dependencies listed for any particular package. Instead the set
+of suggested packages is included in the top-level package set.`,
+	Example: `  # Show all dependencies as a tree
+  pkgr --loglevel=fatal inspect --deps --tree
+  # Show dependency tree, restricting roots to the named packages
+  pkgr --loglevel=fatal inspect --deps --tree processx here
+
+  # Output a JSON record where each item maps a package to its direct
+  # and indirect dependencies
+  pkgr --loglevel=fatal inspect --deps
+  # Do the same, but filter to records for the named packages
+  pkgr --loglevel=fatal inspect --deps processx here
+
+  # Output a JSON record where each item maps a package to
+  # the packages that have it as a dependency
+  pkgr --loglevel=fatal inspect --deps --reverse`,
 	RunE: inspect,
 }
 
@@ -115,8 +134,14 @@ func init() {
 	inspectCmd.Flags().BoolVar(&showDeps, "deps", false, "show dependency tree")
 	inspectCmd.Flags().BoolVar(&reverse, "reverse", false, "show reverse dependencies")
 	inspectCmd.Flags().BoolVar(&tree, "tree", false, "show full recursive dependency tree")
-	inspectCmd.Flags().BoolVar(&toJson, "json", false, "output as clean json")
+	inspectCmd.Flags().BoolVar(&toJson, "json", false,
+		// Point the user to --loglevel because it also suppresses logging
+		// upstream of the inspect() call.
+		"suppress non-fatal logging (note: prefer --loglevel=fatal to this flag)")
 	inspectCmd.Flags().BoolVar(&installedFrom, "installed-from", false, "show package installation source")
 
+	// Don't advertise this until work is done to improve it.
+	inspectCmd.Flags().MarkHidden("installed-from")
+
 	RootCmd.AddCommand(inspectCmd)
 }

cmd/install.go

@@ -35,10 +35,16 @@ import (
 // installCmd represents the R CMD install command
 var installCmd = &cobra.Command{
 	Use:   "install",
-	Short: "install a package",
-	Long: `
-	install a package
-`,
+	Short: "Install packages",
+	Long: `Create the library defined by the configuration file.
+
+See <https://metrumresearchgroup.github.io/pkgr/docs/config> for details on
+the configuration file.`,
+	Example: `  # Create or update library defined by pkgr.yml
+  pkgr install
+  # Install new packages and dependencies but don't update packages that already
+  # exist in the library.
+  pkgr install  --no-update`,
 	RunE: rInstall,
 }
 

cmd/load.go

@@ -21,9 +21,20 @@ import (
 // loadCmd represents the load command
 var loadCmd = &cobra.Command{
 	Use:   "load",
-	Short: "Checks that installed packages can be loaded",
-	Long: `Attempts to load user packages specified in pkgr.yml to validate that each package has been installed
-successfully and can be used. Use the --all flag to load all packages in the user-library dependency tree instead of just user-level packages.`,
+	Short: "Check that installed packages can be loaded",
+	Long: `Load packages specified in the configuration file to validate that
+each package has been installed successfully and can be used.
+
+**Execution environment**. This subcommand runs R with the same settings
+that R would use if you invoked 'R' from the current working directory. It
+relies on that environment being configured to find packages in the library
+path specified in the configuration file (via 'Library' or 'Lockfile:
+Type').  Pass the --json argument to confirm that the package is being
+loaded from the expected library.`,
+	Example: `  # Load packages listed in config file
+  pkgr load --json
+  # Load the above packages and all their dependencies
+  pkgr load --json --all`,
 	Run: func(cmd *cobra.Command, args []string) {
 		all := viper.GetBool("all")
 		json := viper.GetBool("json")
@@ -52,9 +63,9 @@ successfully and can be used. Use the --all flag to load all packages in the use
 
 func init() {
 	RootCmd.AddCommand(loadCmd)
-	loadCmd.Flags().Bool("all", false, "load user packages as well as their dependencies")
+	loadCmd.Flags().Bool("all", false, "load all packages in dependency tree")
 	viper.BindPFlag("all", loadCmd.LocalFlags().Lookup("all")) //There doesn't seem to be a way to bind local flags.
-	loadCmd.Flags().Bool("json", false, "output a JSON object of package info at the end")
+	loadCmd.Flags().Bool("json", false, "output results as a JSON object")
 	viper.BindPFlag("json", loadCmd.LocalFlags().Lookup("json")) //There doesn't seem to be a way to bind local flags.
 	// loadCmd.Flags().BoolP("toggle", "t", false, "Help message for toggle")
 }