Merge pull request #124 from neherlab/feat/cli-ref-docs

feat: handle cli ref docs

Author: ivan-aksamentov

Diff for: .github/workflows/cli.yml

@@ -340,6 +340,35 @@ jobs:
           .\.out\pangraph-x86_64-pc-windows-gnu --help
 
 
+  check-cli-docs:
+    name: "Check that autogenerated CLI documentation is up-to-date"
+    needs: [ build-cli ]
+    runs-on: ubuntu-24.04
+
+    steps:
+      - name: "Checkout code"
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+          submodules: true
+
+      - name: "Download build artifacts"
+        uses: actions/download-artifact@v4
+        with:
+          pattern: pangraph-*
+          merge-multiple: true
+          path: ".out"
+
+      - name: "Re-generate CLI docs"
+        run: |
+          chmod +x ./.out/pangraph-x86_64-unknown-linux-gnu
+          cd docs/
+          ./generate-reference-docs ../.out/pangraph-x86_64-unknown-linux-gnu docs/reference.md
+
+      - name: "Check that the git diff is clean"
+        run: |
+          git -c color.ui=always diff --exit-code 'docs/docs/reference.md' || (echo "Looks like command-line interface has changed, but the autogenerated CLI reference documentation at 'docs/docs/reference.md' is not up-to-date. Please build the fresh version of pangraph, then run 'cd docs && ./generate-reference-docs <path_to_pangraph> docs/docs/reference.md', then verify and commit changes to the file docs/docs/reference.md." >&2; exit 1)
+
 
 #  publish-to-github-releases:
 #    name: "Publish to GitHub Releases"

Diff for: docs/README.md

@@ -47,11 +47,32 @@ bun prod:serve
 The `build` command will produce the directory with HTML, CSS and JS files ready to be deployed to a web hosting. The `serve` command will serve these files on port `5000`.
 
 
-## Command-line reference generation
 
-The `reference.md` file is generated using script `./scripts/update_cli_reference_docs`.
+## Generate command-line reference documentation
+
+The `docs/docs/reference.md` file is generated using script `generate-reference-docs`:
+
+```bash
+cargo build --bin=pangraph
+cd docs
+./generate-reference-docs "../target/debug/pangraph" "docs/docs/reference.md"
+```
+
+> ⚠️ Do not edit the generated file manually! All manual changes will be overwritten by automation.
 
 
 ## Deployment
 
-TODO
+The documentation is automatically deployed on changes to `release-docs` branch. See [.github/workflows/docs.yml](../.github/workflows/docs.yml).
+
+If you have documentation changes on `master` branch, which you want to release to the publicly facing documentation site (https://docs.pangraph.org/), then fast forward `release-docs` to `master`:
+
+```bash
+git checkout release-docs
+git merge --ff-only origin/master
+git push origin release-docs
+```
+
+You can combine it with the software release as well.
+
+> ️⚠️ Make sure your local branches are up-to-date with the remote repo and that they don't have incompatible changes on them. Otherwise the fast-forward merge will fail. When manipulating `release-*` branches, consider using a git GUI application (e.g. GitKraken) to visually check that you do what you think you do. 

Diff for: docs/docs/reference.md

@@ -1,7 +1,18 @@
 ---
 sidebar_position: 9999
 ---
-# CLI commands
+
+# Command-line reference
+
+<!-- WARNING: GENERATED CONTENT -->
+<!-- Do not edit the generated file manually! All manual changes will be overwritten by automation. -->
+<!-- See developer guide for how to properly work with this. -->
+
+:::warning
+Generated content. Report issues at https://github.com/neherlab/pangraph/issues
+:::
+
+
 
 
 This document contains the automatically generated reference documentation for command-line arguments of the latest version of Pangraph CLI.
@@ -258,7 +269,7 @@ Export the core-genome alignment. Note that alignment excludes insertions
 
 Generates a simplified graph that only contains a subset of the input genomes
 
-**Usage:** `pangraph simplify [OPTIONS] [INPUT]`
+**Usage:** `pangraph simplify [OPTIONS] --strains <STRAINS> [INPUT]`
 
 ###### **Arguments:**
 

Diff for: docs/generate-reference-docs

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+set -euo pipefail
+trap "exit" INT
+
+if [ "$#" != 2 ]; then
+  echo "Re-generates CLI reference documentation in Markdown format"
+  echo "Usage: $0 <executable> <output.md>"
+  exit 1
+fi
+
+exe="$1"
+out="$2"
+
+# Add header
+cat << EOF > "${out}"
+---
+sidebar_position: 9999
+---
+
+# Command-line reference
+
+<!-- WARNING: GENERATED CONTENT -->
+<!-- Do not edit the generated file manually! All manual changes will be overwritten by automation. -->
+<!-- See developer guide for how to properly work with this. -->
+
+:::warning
+Generated content. Report issues at https://github.com/neherlab/pangraph/issues
+:::
+
+EOF
+
+# Append body
+./"${exe}" help-markdown >> "${out}"

Diff for: packages/pangraph/src/commands/md_help/print_help_markdown.rs

@@ -6,7 +6,7 @@ use std::borrow::Cow;
 pub fn print_help_markdown() -> Result<(), Report> {
   let help = clap_markdown::help_markdown::<PangraphArgs>();
 
-  let help = replace(&help, "# Command-Line Help for `pangraph`", "# Reference")?;
+  let help = replace(&help, "# Command-Line Help for `pangraph`", "")?;
 
   let help = replace(
     &help,