diff --git a/docs/.github/workflows/check-links.yml b/.github/workflows/docs-check-links.yml similarity index 83% rename from docs/.github/workflows/check-links.yml rename to .github/workflows/docs-check-links.yml index ee0c4e63afd..62f55eac51d 100644 --- a/docs/.github/workflows/check-links.yml +++ b/.github/workflows/docs-check-links.yml @@ -1,9 +1,7 @@ -name: Check Link Validity in Documentation +name: Docs - Check Link Validity on: pull_request: - branches: - - master push: branches: - master @@ -22,9 +20,11 @@ jobs: node-version: '16' # or the version of Node.js you're using - name: Install dependencies + working-directory: docs run: | npm install - name: Run link check + working-directory: docs run: | npm run check-links diff --git a/docs/.github/workflows/validate-nav-build.yml b/.github/workflows/docs-validate-nav-build.yml similarity index 82% rename from docs/.github/workflows/validate-nav-build.yml rename to .github/workflows/docs-validate-nav-build.yml index b5b1a85961d..674ca22a6ae 100644 --- a/docs/.github/workflows/validate-nav-build.yml +++ b/.github/workflows/docs-validate-nav-build.yml @@ -1,9 +1,7 @@ -name: Validate nav.ts Matches nav.js +name: Docs - Validate nav.ts Matches nav.js on: pull_request: - branches: - - master push: branches: - master @@ -23,22 +21,27 @@ jobs: node-version: '16' - name: Install dependencies + working-directory: docs run: | npm install - name: Backup existing nav.js + working-directory: docs run: | mv docs/nav.js docs/nav.js.original - name: Build nav.ts + working-directory: docs run: | npm run build - name: Compare generated nav.js with original nav.js + working-directory: docs run: | diff -q docs/nav.js docs/nav.js.original || (echo "Generated nav.js differs from committed version. Run 'npm run build' and commit the updated file." && exit 1) - name: Restore original nav.js + working-directory: docs if: success() || failure() run: | mv docs/nav.js.original docs/nav.js diff --git a/.github/workflows/pr-only-ci.yml b/.github/workflows/pr-only-ci.yml index 5aab0510c08..74e1a12e68f 100644 --- a/.github/workflows/pr-only-ci.yml +++ b/.github/workflows/pr-only-ci.yml @@ -31,18 +31,12 @@ jobs: 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 + cargo run --features markdown-docs -p spacetimedb-cli > docs/docs/cli-reference.md + cd docs # This is needed because our website doesn't render markdown quite properly. - # See the README in spacetime-docs for more details. + # See the README in 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 diff --git a/docs/.github/workflows/check-cli-reference.yml b/docs/.github/workflows/check-cli-reference.yml deleted file mode 100644 index 65a7b031b3d..00000000000 --- a/docs/.github/workflows/check-cli-reference.yml +++ /dev/null @@ -1,52 +0,0 @@ -on: - pull_request: - push: - branches: - - master - merge_group: - workflow_dispatch: - inputs: - ref: - description: 'SpacetimeDB ref' - required: false - default: '' -permissions: read-all - -name: Check CLI docs - -jobs: - cli_docs: - runs-on: ubuntu-latest - steps: - - name: Find Git ref - shell: bash - run: | - echo "GIT_REF=${{ github.event.inputs.ref || 'master' }}" >>"$GITHUB_ENV" - - name: Checkout sources - uses: actions/checkout@v4 - with: - repository: clockworklabs/SpacetimeDB - ref: ${{ env.GIT_REF }} - - uses: dsherret/rust-toolchain-file@v1 - - name: Checkout docs - uses: actions/checkout@v4 - with: - 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 \2!' 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." - echo "These docs are expected to match exactly the helptext generated by the CLI in SpacetimeDB (${{env.GIT_REF}})." - echo "Once a corresponding change has merged in SpacetimeDB, re-run this check." - echo "See https://github.com/clockworklabs/spacetime-docs/#cli-reference-section for more info on how to generate these docs from SpacetimeDB." - exit 1 - fi diff --git a/docs/README.md b/docs/README.md index b5c6655155d..1b7bcbf42d5 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,3 +1,6 @@ +## Migration note +We are in the process of moving from the `spacetimedb-docs` repo to the `docs` subdirectory of [SpacetimeDB](https://github.com/clockworklabs/SpacetimeDB). **Any new changes should be made there**. The `spacetimedb-docs` repo will only be updated on release. Apologies in advance for any sharp edges while the migration is in progress. + ## SpacetimeDB Documentation This repository contains the markdown files which are used to display documentation on our [website](https://spacetimedb.com/docs). @@ -10,7 +13,8 @@ To make changes to our docs, you can open a pull request in this repository. You 2. Clone your fork: ```bash -git clone ssh://git@github.com//spacetime-docs +git clone ssh://git@github.com//SpacetimeDB +cd SpacetimeDB/docs ``` 3. Make your edits to the docs that you want to make + test them locally @@ -33,7 +37,6 @@ git push -u origin a-branch-name-that-describes-my-change > NOTE! If you make a change to `nav.ts` you will have to run `npm run build` to generate a new `docs/nav.js` file. #### CLI Reference Section -1. Make sure that https://github.com/clockworklabs/SpacetimeDB/pull/2276 is included in your `spacetimedb-cli` binary 1. Run `cargo run --features markdown-docs -p spacetimedb-cli > cli-reference.md` We currently don't properly render markdown backticks and bolding that are inside of headers, so do these two manual replacements to make them look okay (these have only been tested on Linux):