From 175090a49545bd3f2e2610b85148816c5ec7a938 Mon Sep 17 00:00:00 2001 From: Zeke Foppa Date: Tue, 18 Feb 2025 14:22:45 -0800 Subject: [PATCH 01/17] [bfops/cli-docs]: use clap-markdown to print CLI docs in markdown format --- Cargo.lock | 10 ++++++++++ Cargo.toml | 1 + crates/cli/Cargo.toml | 4 ++++ crates/cli/src/main.rs | 9 +++++++++ 4 files changed, 24 insertions(+) diff --git a/Cargo.lock b/Cargo.lock index 4cadb2fc3bd..5e290495812 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -775,6 +775,15 @@ dependencies = [ "clap_derive 4.5.18", ] +[[package]] +name = "clap-markdown" +version = "0.1.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8ebc67e6266e14f8b31541c2f204724fa2ac7ad5c17d6f5908fbb92a60f42cff" +dependencies = [ + "clap 4.5.20", +] + [[package]] name = "clap_builder" version = "4.5.20" @@ -4878,6 +4887,7 @@ dependencies = [ "cargo_metadata", "chrono", "clap 4.5.20", + "clap-markdown", "colored", "convert_case 0.6.0", "dirs", diff --git a/Cargo.toml b/Cargo.toml index b7c3ccea4a3..1ee1fe5a394 100644 --- a/Cargo.toml +++ b/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" diff --git a/crates/cli/Cargo.toml b/crates/cli/Cargo.toml index 8cdc10e714e..52161dedf2a 100644 --- a/crates/cli/Cargo.toml +++ b/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"] } diff --git a/crates/cli/src/main.rs b/crates/cli/src/main.rs index 4fcdfb633ba..1ac05649dcd 100644 --- a/crates/cli/src/main.rs +++ b/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 { // Compute matches before loading the config, because `Config` has an observable `drop` method @@ -31,6 +32,14 @@ async fn main() -> anyhow::Result { exec_subcommand(config, &paths, root_dir, cmd, subcommand_args).await } +#[cfg(feature = "markdown-docs")] +#[tokio::main] +async fn main() -> anyhow::Result { + 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) From 011f41e24e1b4697c3817ba3c0f9506b3142f48a Mon Sep 17 00:00:00 2001 From: Zeke Foppa Date: Tue, 18 Feb 2025 15:34:00 -0800 Subject: [PATCH 02/17] [bfops/cli-docs]: add CI job --- .github/workflows/cli-docs.yml | 50 ++++++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) create mode 100644 .github/workflows/cli-docs.yml diff --git a/.github/workflows/cli-docs.yml b/.github/workflows/cli-docs.yml new file mode 100644 index 00000000000..0c29afc1162 --- /dev/null +++ b/.github/workflows/cli-docs.yml @@ -0,0 +1,50 @@ +on: + pull_request: + merge_group: + workflow_dispatch: + inputs: + pr_number: + description: 'Pull Request Number' + required: false + default: '' + +name: Check CLI Docs + +jobs: + 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 + - uses: actions/setup-dotnet@v4 + with: + global-json-file: modules/global.json + - name: Checkout docs + uses: actions/checkout@v4 + 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 + if ! git diff-index --quiet HEAD; then + echo "It looks like the CLI docs have changed" + git diff + exit 1 + fi From 2489844914b34c10a58b2e2054da6909ecf5d6d6 Mon Sep 17 00:00:00 2001 From: Zeke Foppa Date: Tue, 18 Feb 2025 15:36:04 -0800 Subject: [PATCH 03/17] [bfops/cli-docs]: CI fix? --- .github/workflows/cli-docs.yml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/.github/workflows/cli-docs.yml b/.github/workflows/cli-docs.yml index 0c29afc1162..02ffb57e70e 100644 --- a/.github/workflows/cli-docs.yml +++ b/.github/workflows/cli-docs.yml @@ -1,6 +1,5 @@ on: pull_request: - merge_group: workflow_dispatch: inputs: pr_number: @@ -36,9 +35,10 @@ jobs: global-json-file: modules/global.json - name: Checkout docs uses: actions/checkout@v4 - repository: clockworklabs/spacetime-docs - ref: master - path: spacetime-docs + 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 From 8b85ee25124639f4900817fb44a8f91462309d12 Mon Sep 17 00:00:00 2001 From: Zeke Foppa Date: Tue, 18 Feb 2025 15:37:43 -0800 Subject: [PATCH 04/17] [bfops/cli-docs]: tweak CI --- .github/workflows/{cli-docs.yml => pr-only-ci.yml} | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) rename .github/workflows/{cli-docs.yml => pr-only-ci.yml} (97%) diff --git a/.github/workflows/cli-docs.yml b/.github/workflows/pr-only-ci.yml similarity index 97% rename from .github/workflows/cli-docs.yml rename to .github/workflows/pr-only-ci.yml index 02ffb57e70e..9078dee8c4f 100644 --- a/.github/workflows/cli-docs.yml +++ b/.github/workflows/pr-only-ci.yml @@ -7,10 +7,11 @@ on: required: false default: '' -name: Check CLI Docs +name: PR-only CI jobs: cli_docs: + name: Check CLI docs runs-on: ubuntu-latest steps: - name: Find Git ref From 0e6e347f321d339a26e054cbb3cbe0e280feb907 Mon Sep 17 00:00:00 2001 From: Zeke Foppa Date: Tue, 18 Feb 2025 15:43:04 -0800 Subject: [PATCH 05/17] [bfops/cli-docs]: add sed commands from README --- .github/workflows/pr-only-ci.yml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/.github/workflows/pr-only-ci.yml b/.github/workflows/pr-only-ci.yml index 9078dee8c4f..111a6f51d76 100644 --- a/.github/workflows/pr-only-ci.yml +++ b/.github/workflows/pr-only-ci.yml @@ -44,6 +44,10 @@ jobs: 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 \2!' docs/cli-reference.md if ! git diff-index --quiet HEAD; then echo "It looks like the CLI docs have changed" git diff From 624c5cd2064eb1139aa231ad001d0077c7ac8140 Mon Sep 17 00:00:00 2001 From: Zeke Foppa Date: Tue, 18 Feb 2025 15:46:11 -0800 Subject: [PATCH 06/17] [bfops/cli-docs]: update CI --- .github/workflows/pr-only-ci.yml | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/.github/workflows/pr-only-ci.yml b/.github/workflows/pr-only-ci.yml index 111a6f51d76..06d463bf243 100644 --- a/.github/workflows/pr-only-ci.yml +++ b/.github/workflows/pr-only-ci.yml @@ -48,7 +48,10 @@ jobs: # See the README in spacetime-docs for more details. sed -i'' -E 's!^(##) `(.*)`$!\1 \2!' docs/cli-reference.md sed -i'' -E 's!^(######) \*\*(.*)\*\*$!\1 \2!' docs/cli-reference.md - if ! git diff-index --quiet HEAD; then + if git diff-index --quiet HEAD; then + echo "No docs changes detected" + git status + else echo "It looks like the CLI docs have changed" git diff exit 1 From 34087fa5ecdbc77a46a6e24dce366270d6c2bb58 Mon Sep 17 00:00:00 2001 From: Zeke Foppa Date: Tue, 18 Feb 2025 17:03:29 -0800 Subject: [PATCH 07/17] [bfops/cli-docs]: [temp] change the CLI helptext to check that CI fails --- crates/cli/src/subcommands/server.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crates/cli/src/subcommands/server.rs b/crates/cli/src/subcommands/server.rs index 611919a6385..a746316a1c4 100644 --- a/crates/cli/src/subcommands/server.rs +++ b/crates/cli/src/subcommands/server.rs @@ -17,7 +17,7 @@ pub fn cli() -> Command { .subcommand_required(true) .subcommands(get_subcommands()) .about(format!( - "Manage the connection to the SpacetimeDB server. {}", + "Manage the connection to the SpacetimeDB server. FOO. {}", UNSTABLE_WARNING )) } From 6d8a787bce827258ca3c7adc06ea1d1347a3e7a3 Mon Sep 17 00:00:00 2001 From: Zeke Foppa Date: Tue, 18 Feb 2025 17:03:42 -0800 Subject: [PATCH 08/17] [bfops/cli-docs]: revert --- crates/cli/src/subcommands/server.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crates/cli/src/subcommands/server.rs b/crates/cli/src/subcommands/server.rs index a746316a1c4..611919a6385 100644 --- a/crates/cli/src/subcommands/server.rs +++ b/crates/cli/src/subcommands/server.rs @@ -17,7 +17,7 @@ pub fn cli() -> Command { .subcommand_required(true) .subcommands(get_subcommands()) .about(format!( - "Manage the connection to the SpacetimeDB server. FOO. {}", + "Manage the connection to the SpacetimeDB server. {}", UNSTABLE_WARNING )) } From 61b6e99fa13b6a2f7a6161b75058ca5b4b9ab513 Mon Sep 17 00:00:00 2001 From: Zeke Foppa Date: Tue, 18 Feb 2025 17:04:32 -0800 Subject: [PATCH 09/17] [bfops/cli-docs]: remove unnecessary dotnet setup --- .github/workflows/pr-only-ci.yml | 3 --- 1 file changed, 3 deletions(-) diff --git a/.github/workflows/pr-only-ci.yml b/.github/workflows/pr-only-ci.yml index 06d463bf243..30c3612e23a 100644 --- a/.github/workflows/pr-only-ci.yml +++ b/.github/workflows/pr-only-ci.yml @@ -31,9 +31,6 @@ jobs: with: ref: ${{ env.GIT_REF }} - uses: dsherret/rust-toolchain-file@v1 - - uses: actions/setup-dotnet@v4 - with: - global-json-file: modules/global.json - name: Checkout docs uses: actions/checkout@v4 with: From a1cd79fcaad5ee613fecdc1cdf95f1298a7d2322 Mon Sep 17 00:00:00 2001 From: Zeke Foppa Date: Tue, 18 Feb 2025 17:10:26 -0800 Subject: [PATCH 10/17] [bfops/cli-docs]: empty From 968fa0121073e28898533c9c5038b0dfb625e047 Mon Sep 17 00:00:00 2001 From: Zeke Foppa Date: Tue, 18 Feb 2025 17:11:41 -0800 Subject: [PATCH 11/17] [bfops/cli-docs]: tweak --- .github/workflows/pr-only-ci.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/pr-only-ci.yml b/.github/workflows/pr-only-ci.yml index 30c3612e23a..b20ef5dbb52 100644 --- a/.github/workflows/pr-only-ci.yml +++ b/.github/workflows/pr-only-ci.yml @@ -49,7 +49,7 @@ jobs: echo "No docs changes detected" git status else - echo "It looks like the CLI docs have changed" + echo "It looks like the CLI docs have changed:" git diff exit 1 fi From 4848880ee3a16b66456cbc03d3cf7fe777bad75f Mon Sep 17 00:00:00 2001 From: Zeke Foppa Date: Tue, 18 Feb 2025 19:46:15 -0800 Subject: [PATCH 12/17] [bfops/cli-docs]: ci always git status --- .github/workflows/pr-only-ci.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/pr-only-ci.yml b/.github/workflows/pr-only-ci.yml index b20ef5dbb52..588e759e0d2 100644 --- a/.github/workflows/pr-only-ci.yml +++ b/.github/workflows/pr-only-ci.yml @@ -45,9 +45,9 @@ jobs: # See the README in spacetime-docs for more details. sed -i'' -E 's!^(##) `(.*)`$!\1 \2!' docs/cli-reference.md sed -i'' -E 's!^(######) \*\*(.*)\*\*$!\1 \2!' docs/cli-reference.md + git status if git diff-index --quiet HEAD; then echo "No docs changes detected" - git status else echo "It looks like the CLI docs have changed:" git diff From bc8f72672e0a41025d1c4ae193815b27e8251abd Mon Sep 17 00:00:00 2001 From: Zeke Foppa Date: Tue, 18 Feb 2025 19:49:27 -0800 Subject: [PATCH 13/17] [bfops/cli-docs]: fix CI? --- .github/workflows/pr-only-ci.yml | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/.github/workflows/pr-only-ci.yml b/.github/workflows/pr-only-ci.yml index 588e759e0d2..5aab0510c08 100644 --- a/.github/workflows/pr-only-ci.yml +++ b/.github/workflows/pr-only-ci.yml @@ -46,10 +46,9 @@ jobs: sed -i'' -E 's!^(##) `(.*)`$!\1 \2!' docs/cli-reference.md sed -i'' -E 's!^(######) \*\*(.*)\*\*$!\1 \2!' docs/cli-reference.md git status - if git diff-index --quiet HEAD; then + if git diff --exit-code HEAD; then echo "No docs changes detected" else echo "It looks like the CLI docs have changed:" - git diff exit 1 fi From 1a446ac13b9e7a1fd271dc9abc466a6ca1b9fa4b Mon Sep 17 00:00:00 2001 From: Zeke Foppa Date: Tue, 18 Feb 2025 19:51:21 -0800 Subject: [PATCH 14/17] [bfops/cli-docs]: REVERT THIS COMMIT - test that CI fails --- crates/cli/src/subcommands/server.rs | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/crates/cli/src/subcommands/server.rs b/crates/cli/src/subcommands/server.rs index 611919a6385..ae58d410eab 100644 --- a/crates/cli/src/subcommands/server.rs +++ b/crates/cli/src/subcommands/server.rs @@ -16,10 +16,7 @@ pub fn cli() -> Command { .args_conflicts_with_subcommands(true) .subcommand_required(true) .subcommands(get_subcommands()) - .about(format!( - "Manage the connection to the SpacetimeDB server. {}", - UNSTABLE_WARNING - )) + .about(format!("ARGLEBARGLE {}", UNSTABLE_WARNING)) } fn get_subcommands() -> Vec { From adb70eda3c7cb19da9cfe7d9d179eca85d7653ce Mon Sep 17 00:00:00 2001 From: Zeke Foppa Date: Tue, 18 Feb 2025 19:51:28 -0800 Subject: [PATCH 15/17] [bfops/cli-docs]: revert --- crates/cli/src/subcommands/server.rs | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/crates/cli/src/subcommands/server.rs b/crates/cli/src/subcommands/server.rs index ae58d410eab..611919a6385 100644 --- a/crates/cli/src/subcommands/server.rs +++ b/crates/cli/src/subcommands/server.rs @@ -16,7 +16,10 @@ pub fn cli() -> Command { .args_conflicts_with_subcommands(true) .subcommand_required(true) .subcommands(get_subcommands()) - .about(format!("ARGLEBARGLE {}", UNSTABLE_WARNING)) + .about(format!( + "Manage the connection to the SpacetimeDB server. {}", + UNSTABLE_WARNING + )) } fn get_subcommands() -> Vec { From 149bec13ad643e58d0e60b810c52081e250737d0 Mon Sep 17 00:00:00 2001 From: Zeke Foppa Date: Tue, 18 Feb 2025 19:51:21 -0800 Subject: [PATCH 16/17] [bfops/cli-docs]: [bfops/cli-docs]: REVERT THIS COMMIT - test that CI fails --- crates/cli/src/subcommands/server.rs | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/crates/cli/src/subcommands/server.rs b/crates/cli/src/subcommands/server.rs index 611919a6385..ae58d410eab 100644 --- a/crates/cli/src/subcommands/server.rs +++ b/crates/cli/src/subcommands/server.rs @@ -16,10 +16,7 @@ pub fn cli() -> Command { .args_conflicts_with_subcommands(true) .subcommand_required(true) .subcommands(get_subcommands()) - .about(format!( - "Manage the connection to the SpacetimeDB server. {}", - UNSTABLE_WARNING - )) + .about(format!("ARGLEBARGLE {}", UNSTABLE_WARNING)) } fn get_subcommands() -> Vec { From 01e06b63469aef5eb94e31176cfbc4a596ec85b8 Mon Sep 17 00:00:00 2001 From: Zeke Foppa Date: Tue, 18 Feb 2025 20:03:57 -0800 Subject: [PATCH 17/17] [bfops/cli-docs]: revert --- crates/cli/src/subcommands/server.rs | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/crates/cli/src/subcommands/server.rs b/crates/cli/src/subcommands/server.rs index ae58d410eab..611919a6385 100644 --- a/crates/cli/src/subcommands/server.rs +++ b/crates/cli/src/subcommands/server.rs @@ -16,7 +16,10 @@ pub fn cli() -> Command { .args_conflicts_with_subcommands(true) .subcommand_required(true) .subcommands(get_subcommands()) - .about(format!("ARGLEBARGLE {}", UNSTABLE_WARNING)) + .about(format!( + "Manage the connection to the SpacetimeDB server. {}", + UNSTABLE_WARNING + )) } fn get_subcommands() -> Vec {