CLI - Add feature to print markdown docs

.github/workflows/pr-only-ci.yml

@@ -0,0 +1,54 @@
+on:
+  pull_request:
+  workflow_dispatch:
+    inputs:
+      pr_number:
+        description: 'Pull Request Number'
+        required: false
+        default: ''
+
+name: PR-only CI
+
+jobs:
+  cli_docs:
+    name: Check CLI docs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Find Git ref
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        shell: bash
+        run: |
+          PR_NUMBER="${{ github.event.inputs.pr_number || null }}"
+          if test -n "${PR_NUMBER}"; then
+            GIT_REF="$( gh pr view --repo clockworklabs/SpacetimeDB $PR_NUMBER --json headRefName --jq .headRefName )"
+          else
+            GIT_REF="${{ github.ref }}"
+          fi
+          echo "GIT_REF=${GIT_REF}" >>"$GITHUB_ENV"
+      - name: Checkout sources
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ env.GIT_REF }}
+      - uses: dsherret/rust-toolchain-file@v1
+      - name: Checkout docs
+        uses: actions/checkout@v4
+        with:
+          repository: clockworklabs/spacetime-docs
+          ref: master
+          path: spacetime-docs
+      - name: Check for docs change
+        run: |
+          cargo run --features markdown-docs -p spacetimedb-cli > spacetime-docs/docs/cli-reference.md
+          cd spacetime-docs
+          # This is needed because our website doesn't render markdown quite properly.
+          # See the README in spacetime-docs for more details.
+          sed -i'' -E 's!^(##) `(.*)`$!\1 \2!' docs/cli-reference.md
+          sed -i'' -E 's!^(######) \*\*(.*)\*\*$!\1 <b>\2</b>!' docs/cli-reference.md
+          git status
+          if git diff --exit-code HEAD; then
+            echo "No docs changes detected"
+          else
+            echo "It looks like the CLI docs have changed:"
+            exit 1
+          fi

Cargo.toml

@@ -140,6 +140,7 @@ bytestring = { version = "1.2.0", features = ["serde"] }
 cargo_metadata = "0.17.0"
 chrono = { version = "0.4.24", default-features = false }
 clap = { version = "4.2.4", features = ["derive", "wrap_help"] }
+clap-markdown = "0.1.4"
 colored = "2.0.0"
 console = { version = "0.15.6" }
 convert_case = "0.6.0"

crates/cli/Cargo.toml

@@ -6,6 +6,9 @@ license-file = "LICENSE"
 description = "A command line interface for SpacetimeDB"
 rust-version.workspace = true
 
+[features]
+markdown-docs = []
+
 [lib]
 bench = false
 
@@ -70,6 +73,7 @@ walkdir.workspace = true
 wasmbin.workspace = true
 wasmtime.workspace = true
 webbrowser.workspace = true
+clap-markdown.workspace = true
 
 [target.'cfg(windows)'.dependencies]
 windows-sys = { workspace = true, features = ["Win32_System_Console"] }

crates/cli/src/main.rs

@@ -9,6 +9,7 @@ use spacetimedb_paths::{RootDir, SpacetimePaths};
 #[global_allocator]
 static GLOBAL: MiMalloc = MiMalloc;
 
+#[cfg(not(feature = "markdown-docs"))]
 #[tokio::main]
 async fn main() -> anyhow::Result<ExitCode> {
     // Compute matches before loading the config, because `Config` has an observable `drop` method
@@ -31,6 +32,14 @@ async fn main() -> anyhow::Result<ExitCode> {
     exec_subcommand(config, &paths, root_dir, cmd, subcommand_args).await
 }
 
+#[cfg(feature = "markdown-docs")]
+#[tokio::main]
+async fn main() -> anyhow::Result<ExitCode> {
+    let markdown = clap_markdown::help_markdown_command(&get_command());
+    println!("{}", markdown);
+    Ok(ExitCode::SUCCESS)
+}
+
 fn get_command() -> Command {
     Command::new("spacetime")
         .version(version::CLI_VERSION)