docs: publish Rust, gRPC, and JS/TS API docs on GitHub Pages#3157
Merged
Conversation
Expand the book.yml workflow to build comprehensive API documentation alongside the mdBook, deployed at dashpay.github.io/platform/api/. - Add parallel CI jobs for cargo doc (Rust), protoc-gen-doc (gRPC), and TypeDoc (JS/TS) that run alongside the existing mdBook build - Add API Reference appendix page to the book's table of contents - Add dark-themed protoc-gen-doc HTML template matching the book style - Add TypeDoc configuration for js-dash-sdk, wasm-dpp, and wasm-sdk - Add rustdoc CSS overrides with Dash brand colors - Remove dead docs.yml workflow (targeted obsolete v1.0-dev branch) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Rust: Remove stale target/doc cache that caused search index corruption, and use absolute path for --extend-css to ensure it resolves in CI. JS/TS: Use a dedicated tsconfig with skipLibCheck and path mappings for @dashevo/wasm-dpp instead of trying to build wasm-dpp types (which requires the Rust WASM toolchain). Document js-dash-sdk source directly. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Contributor
📝 WalkthroughWalkthroughConverts a single docs workflow into four parallel GitHub Actions build jobs (mdBook, Rust, gRPC, JS) producing named artifacts; deploy now depends on all builds, downloads and assembles artifacts into a unified Changes
Sequence Diagram(s)sequenceDiagram
participant GH as GitHub Actions
participant BuildBook as build-book
participant RustDocs as build-rust-docs
participant GrpcDocs as build-grpc-docs
participant JsDocs as build-js-docs
participant Deploy as deploy
GH->>BuildBook: start
GH->>RustDocs: start
GH->>GrpcDocs: start
GH->>JsDocs: start
BuildBook-->>GH: upload `book-output`
RustDocs-->>GH: upload `rust-docs`
GrpcDocs-->>GH: upload `grpc-docs`
JsDocs-->>GH: upload `js-docs`
GH->>Deploy: trigger when all complete
Deploy->>GH: download all artifacts
Deploy->>Deploy: assemble `_site` (book + api docs)
Deploy-->>GH: upload Pages artifact / publish
Estimated code review effort🎯 4 (Complex) | ⏱️ ~45 minutes Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Contributor
There was a problem hiding this comment.
Pull request overview
This PR updates the documentation publishing pipeline to deploy the mdBook plus generated API reference documentation (Rust rustdoc, gRPC proto docs, and JS/TS TypeDoc) to GitHub Pages under a unified site structure.
Changes:
- Expands
.github/workflows/book.ymlto build mdBook + Rust + gRPC + JS/TS docs in parallel and assemble them into a single_sitefor Pages deployment. - Adds new documentation assets/config: TypeDoc config, rustdoc CSS overrides, and a custom HTML template for
protoc-gen-doc. - Adds an “API Reference” appendix page to the mdBook and removes the obsolete
.github/workflows/docs.yml.
Reviewed changes
Copilot reviewed 8 out of 8 changed files in this pull request and generated 9 comments.
Show a summary per file
| File | Description |
|---|---|
.github/workflows/book.yml |
Adds parallel doc build jobs + assembly/deploy logic for GitHub Pages. |
.github/workflows/docs.yml |
Removes the old workflow targeting v1.0-dev. |
docs/typedoc.json |
Defines TypeDoc entry points across multiple JS/TS/WASM packages. |
docs/rust-extra.css |
Adds branding overrides for rustdoc output styling. |
docs/grpc/template.html |
Custom dark-themed HTML template for generated gRPC docs. |
book/src/api-reference.md |
Adds an API reference page linking to generated doc sections. |
book/src/SUMMARY.md |
Adds an Appendix section with the new API reference page. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Rust: Add -j1 to cargo doc to avoid parallel search index race condition that corrupts target/doc/search.index. JS/TS: Replace custom nodejs action with direct setup-node and YARN_ENABLE_SCRIPTS=false to skip native module compilation (ssh2/nan fail on Node 24 V8 API and aren't needed for TypeDoc). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Fix relative paths in typedoc.json and tsconfig.typedoc.json (paths are resolved relative to the config file location in docs/). Add skipErrorChecking to avoid TS type errors in cross-package imports. Verified locally: TypeDoc generates output successfully. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 5
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.github/workflows/book.yml:
- Around line 7-15: The current paths filter in .github/workflows/book.yml is
too narrow and can miss doc rebuilds when only manifests/lockfiles change;
update the workflow's paths: block to include common manifest and lockfile names
(e.g., package.json, package-lock.json, yarn.lock, pnpm-lock.yaml, Cargo.toml,
Cargo.lock), repo-level docs and markdown (e.g., README.md, docs/**/*.md,
book/**, docs/**), documentation site config files (e.g., mkdocs.yml,
docusaurus.config.js), and any package-level manifests (e.g.,
packages/**/package.json) so updates to dependencies or configs trigger the doc
build; modify the paths: entry in .github/workflows/book.yml accordingly.
- Around line 115-120: Replace the unpinned image
pseudomuto/protoc-gen-doc:latest used in the docker run step with a specific
version tag or immutable digest (e.g., pseudomuto/protoc-gen-doc:<version> or
pseudomuto/protoc-gen-doc@sha256:<digest>) to make the workflow reproducible;
update the docker invocation where pseudomuto/protoc-gen-doc:latest appears and
choose a released tag or SHA that you trust (consistent with how
rvolosatovs/protoc:4.0.0 is pinned elsewhere).
- Around line 145-147: Add TypeDoc as a pinned devDependency in package.json
(e.g., "typedoc": "<exact-version>" matching your lockfile) so CI uses a
deterministic install, then update the workflow step in
.github/workflows/book.yml to remove the ad-hoc `yarn add --dev typedoc` and
instead rely on the repo install (run `yarn install --frozen-lockfile` or the
existing `yarn install --inline-builds` earlier in the job) and invoke TypeDoc
with `yarn typedoc --options docs/typedoc.json --out /tmp/js-out`; ensure the
package.json entry is committed so `yarn typedoc` is available in CI.
In `@book/src/api-reference.md`:
- Around line 3-4: Update the second sentence that currently claims "Each
section is built from source and updated on every push to `v*-dev` branches." to
accurately state that the API docs are regenerated only when matching path
changes occur on `v*-dev` branches (e.g., "Each section is built from source and
updated only when relevant path changes are pushed to `v*-dev` branches"). Edit
the lines containing the sentences starting "Auto-generated API documentation
for the Dash Platform developer ecosystem." and the following sentence to
replace the overstated frequency with this clarified wording.
In `@docs/grpc/template.html`:
- Around line 185-189: The ToC loop {{range .Extensions}} is producing a
duplicate "File-level Extensions" link per extension; replace the range with a
single conditional that renders one list item when Extensions is non-empty
(e.g., use {{if .Extensions}} or an equivalent non-empty check) and keep the
existing anchor "#{{$file_name}}-extensions" and label "<span
class=\"badge\">X</span>File-level Extensions" inside that single list item so
the entry appears once.
ℹ️ Review info
Configuration used: defaults
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (8)
.github/workflows/book.yml.github/workflows/docs.ymlbook/src/SUMMARY.mdbook/src/api-reference.mddocs/grpc/template.htmldocs/rust-extra.cssdocs/tsconfig.typedoc.jsondocs/typedoc.json
💤 Files with no reviewable changes (1)
- .github/workflows/docs.yml
Use `toolchain: stable` (currently 1.93) instead of the project's pinned 1.92 to pick up the rustdoc search index fix (rust-lang/rust#148563). Remove the -j1 workaround since parallel doc generation works on 1.93+. Also cancel in-progress runs on the same branch. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
The rust-toolchain.toml (pinned to 1.92) overrides the installed toolchain. Set RUSTUP_TOOLCHAIN=stable env var on the doc build step to force stable (1.93+) which has the search index fix. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
lklimek
had a problem deploying
to
github-pages
GitHub Actions
Failure
Contributor
There was a problem hiding this comment.
♻️ Duplicate comments (3)
.github/workflows/book.yml (3)
154-157:⚠️ Potential issue | 🟠 MajorAvoid ad-hoc TypeDoc installation in CI.
At Line 156,
yarn add --dev typedocintroduces nondeterministic dependency resolution and mutates dependency state during the run.🛠️ Suggested workflow fix
- name: Generate TypeDoc run: | - yarn add --dev typedoc yarn typedoc --options docs/typedoc.json --out /tmp/js-outAlso add a pinned
typedocentry indevDependencies(outside this file) and lock it inyarn.lock.Use this read-only verification to confirm it is pinned before relying on
yarn typedoc:#!/bin/bash set -euo pipefail echo "Checking package.json files for pinned typedoc devDependency..." fd '^package.json$' -x rg -n --no-heading '"typedoc"\s*:\s*"[^"]+"' {} echo echo "Checking lockfile entries for typedoc resolution..." rg -n --no-heading '^"?typedoc@' yarn.lock || true🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.github/workflows/book.yml around lines 154 - 157, The CI step "Generate TypeDoc" currently runs an ad-hoc install via `yarn add --dev typedoc` which mutates dependencies and causes nondeterminism; remove that `yarn add --dev typedoc` line from the workflow and instead pin `typedoc` in package.json devDependencies and commit the resulting yarn.lock entry so CI uses the locked version; keep the `yarn typedoc --options docs/typedoc.json --out /tmp/js-out` invocation but ensure the repository's package.json and yarn.lock contain a specific `typedoc` version (verify with the provided read-only checks before relying on `yarn typedoc`).
117-122:⚠️ Potential issue | 🟠 MajorPin
pseudomuto/protoc-gen-docto a fixed tag or digest.At Line 121,
:latestmakes doc builds non-reproducible and vulnerable to upstream image drift.🛠️ Suggested fix
- pseudomuto/protoc-gen-doc:latest \ + pseudomuto/protoc-gen-doc:<pinned-version-or-digest> \What is the latest stable release tag (and immutable digest) for the Docker image `pseudomuto/protoc-gen-doc`?🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.github/workflows/book.yml around lines 117 - 122, Replace the floating image tag in the docker run command (pseudomuto/protoc-gen-doc:latest) with a fixed, immutable reference: either a specific release tag (e.g., pseudomuto/protoc-gen-doc:<RELEASE_TAG>) or, preferably, the image digest (pseudomuto/protoc-gen-doc@sha256:<DIGEST>). Locate the docker run block that mounts /protos, /templates/template.html and /out and update the image reference accordingly after looking up the latest stable release tag or its sha256 digest on Docker Hub or the upstream repository; use the digest for reproducible builds.
7-15:⚠️ Potential issue | 🟠 MajorExpand trigger paths to include manifest/lockfile-driven doc changes.
At Line 7, current path filters can still skip docs rebuilds when only dependency manifests/lockfiles change, which can leave published API docs stale.
🛠️ Suggested trigger expansion
paths: - 'book/**' - 'docs/**' + - 'Cargo.toml' + - 'Cargo.lock' + - 'packages/**/Cargo.toml' - 'packages/**/*.rs' - 'packages/dapi-grpc/protos/**' + - 'package.json' + - 'yarn.lock' + - 'packages/**/package.json' - 'packages/js-dash-sdk/src/**' - 'packages/wasm-dpp/lib/**' - 'packages/wasm-sdk/dist/**/*.d.ts' - '.github/workflows/book.yml'🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.github/workflows/book.yml around lines 7 - 15, The workflow's paths filter under paths: currently misses dependency manifest/lockfile changes; update the list to include common manifest/lockfile patterns so docs rebuilds run when deps change (e.g., add '**/package.json', '**/package-lock.json', '**/pnpm-lock.yaml', '**/yarn.lock', '**/Cargo.toml', '**/Cargo.lock', '**/go.mod', '**/go.sum', '**/pyproject.toml', '**/requirements.txt' alongside the existing entries) so the book workflow in .github/workflows/book.yml triggers on manifest-driven doc changes.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Duplicate comments:
In @.github/workflows/book.yml:
- Around line 154-157: The CI step "Generate TypeDoc" currently runs an ad-hoc
install via `yarn add --dev typedoc` which mutates dependencies and causes
nondeterminism; remove that `yarn add --dev typedoc` line from the workflow and
instead pin `typedoc` in package.json devDependencies and commit the resulting
yarn.lock entry so CI uses the locked version; keep the `yarn typedoc --options
docs/typedoc.json --out /tmp/js-out` invocation but ensure the repository's
package.json and yarn.lock contain a specific `typedoc` version (verify with the
provided read-only checks before relying on `yarn typedoc`).
- Around line 117-122: Replace the floating image tag in the docker run command
(pseudomuto/protoc-gen-doc:latest) with a fixed, immutable reference: either a
specific release tag (e.g., pseudomuto/protoc-gen-doc:<RELEASE_TAG>) or,
preferably, the image digest (pseudomuto/protoc-gen-doc@sha256:<DIGEST>). Locate
the docker run block that mounts /protos, /templates/template.html and /out and
update the image reference accordingly after looking up the latest stable
release tag or its sha256 digest on Docker Hub or the upstream repository; use
the digest for reproducible builds.
- Around line 7-15: The workflow's paths filter under paths: currently misses
dependency manifest/lockfile changes; update the list to include common
manifest/lockfile patterns so docs rebuilds run when deps change (e.g., add
'**/package.json', '**/package-lock.json', '**/pnpm-lock.yaml', '**/yarn.lock',
'**/Cargo.toml', '**/Cargo.lock', '**/go.mod', '**/go.sum', '**/pyproject.toml',
'**/requirements.txt' alongside the existing entries) so the book workflow in
.github/workflows/book.yml triggers on manifest-driven doc changes.
ℹ️ Review info
Configuration used: defaults
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (3)
.github/workflows/book.ymldocs/tsconfig.typedoc.jsondocs/typedoc.json
🚧 Files skipped from review as they are similar to previous changes (1)
- docs/typedoc.json
Move typedoc from ad-hoc CI install to a proper pinned devDependency so the version is locked in yarn.lock. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Pin protoc-gen-doc Docker image to sha256 digest - Remove ad-hoc typedoc install, use pinned devDependency - Fix api-reference.md wording about update frequency - Add Cargo.toml and package.json to workflow trigger paths - Fix duplicate ToC entries in gRPC template (range → if) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…espace Crate names in the API reference table now link to their respective rustdoc pages. TypeDoc entry point changed from index.ts (which used `export = SDK`) to SDK/SDK.ts to eliminate the spurious "export=" namespace in the JS docs sidebar. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
♻️ Duplicate comments (1)
.github/workflows/book.yml (1)
7-18:⚠️ Potential issue | 🟠 MajorExpand trigger paths for lockfiles/root manifest to avoid stale published docs.
On Lines 7-18, doc generation can still be skipped when only
Cargo.lock,yarn.lock, or rootpackage.jsonchanges, even though those changes can alter generated Rust/JS API docs.🛠️ Suggested path filter patch
paths: - 'book/**' - 'docs/**' - 'Cargo.toml' + - 'Cargo.lock' + - 'package.json' + - 'yarn.lock' - 'packages/**/Cargo.toml' + - 'packages/**/package.json' - 'packages/**/*.rs' - 'packages/dapi-grpc/protos/**' - 'packages/js-dash-sdk/src/**' - 'packages/js-dash-sdk/package.json' - 'packages/wasm-dpp/lib/**' - 'packages/wasm-sdk/dist/**/*.d.ts' - '.github/workflows/book.yml'🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.github/workflows/book.yml around lines 7 - 18, The paths filter in the workflow's "paths" block is missing triggers for lockfiles and the root JS manifest so doc generation can be skipped when only dependency files change; update the paths list in .github/workflows/book.yml by adding patterns for Cargo.lock, yarn.lock (and/or **/yarn.lock), and the root package.json (and/or **/package-lock.json) so changes to those files will run the docs workflow; edit the existing paths block (the entries shown in the diff) to include these additional patterns.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Duplicate comments:
In @.github/workflows/book.yml:
- Around line 7-18: The paths filter in the workflow's "paths" block is missing
triggers for lockfiles and the root JS manifest so doc generation can be skipped
when only dependency files change; update the paths list in
.github/workflows/book.yml by adding patterns for Cargo.lock, yarn.lock (and/or
**/yarn.lock), and the root package.json (and/or **/package-lock.json) so
changes to those files will run the docs workflow; edit the existing paths block
(the entries shown in the diff) to include these additional patterns.
ℹ️ Review info
Configuration used: defaults
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (18)
.yarn/cache/@gerrit0-mini-shiki-npm-3.22.0-61363e5c63-c81a6320f9.zipis excluded by!**/.yarn/**,!**/*.zip.yarn/cache/@shikijs-engine-oniguruma-npm-3.23.0-f52e834e22-edd8983be8.zipis excluded by!**/.yarn/**,!**/*.zip.yarn/cache/@shikijs-langs-npm-3.23.0-fedddc6cdb-115b1afb9e.zipis excluded by!**/.yarn/**,!**/*.zip.yarn/cache/@shikijs-themes-npm-3.23.0-24d63f0d75-7419873804.zipis excluded by!**/.yarn/**,!**/*.zip.yarn/cache/@shikijs-types-npm-3.23.0-88a7be728c-18b5703d44.zipis excluded by!**/.yarn/**,!**/*.zip.yarn/cache/@shikijs-vscode-textmate-npm-10.0.2-c80a8c15da-d924cba8a0.zipis excluded by!**/.yarn/**,!**/*.zip.yarn/cache/@types-hast-npm-3.0.4-640776a343-732920d81b.zipis excluded by!**/.yarn/**,!**/*.zip.yarn/cache/@types-unist-npm-3.0.3-1c20461f2e-96e6453da9.zipis excluded by!**/.yarn/**,!**/*.zip.yarn/cache/entities-npm-4.5.0-7cdb83b832-ede2a35c9b.zipis excluded by!**/.yarn/**,!**/*.zip.yarn/cache/linkify-it-npm-5.0.0-adb5f9c96f-ef3b7609dd.zipis excluded by!**/.yarn/**,!**/*.zip.yarn/cache/lunr-npm-2.3.9-fa3aa9c2d6-f2f6db34c0.zipis excluded by!**/.yarn/**,!**/*.zip.yarn/cache/markdown-it-npm-14.1.1-45c173274d-088822c8aa.zipis excluded by!**/.yarn/**,!**/*.zip.yarn/cache/mdurl-npm-2.0.0-3259713daf-1720349d4a.zipis excluded by!**/.yarn/**,!**/*.zip.yarn/cache/punycode.js-npm-2.3.1-9084ecbbf5-f0e946d1ed.zipis excluded by!**/.yarn/**,!**/*.zip.yarn/cache/typedoc-npm-0.28.17-17c807e9f1-09bf15a30c.zipis excluded by!**/.yarn/**,!**/*.zip.yarn/cache/uc.micro-npm-2.1.0-c45282c865-3719735824.zipis excluded by!**/.yarn/**,!**/*.zip.yarn/cache/yaml-npm-2.8.2-6cbf7c73c4-4eab0074da.zipis excluded by!**/.yarn/**,!**/*.zipyarn.lockis excluded by!**/yarn.lock,!**/*.lock
📒 Files selected for processing (6)
.github/workflows/book.yml.pnp.cjsbook/src/api-reference.mddocs/grpc/template.htmldocs/typedoc.jsonpackage.json
🚧 Files skipped from review as they are similar to previous changes (1)
- docs/typedoc.json
lklimek
added
the
ready for final review
QuantumExplorer
approved these changes
Feb 25, 2026
Member
|
Nice |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
TL;DR
https://dashpay.github.io/platform/api-reference.html
If this doesn't work, trigger https://github.com/dashpay/platform/actions/workflows/book.yml on
feat/api-docsbranch (most likely overwritten by merge to 3.1-dev)Summary
book.ymlworkflow to build and deploy comprehensive API documentation atdashpay.github.io/platform/api/alongside the existing mdBookcargo doc), gRPC (protoc-gen-doc), and JS/TS (TypeDoc) API docsdocs.ymlworkflow that targeted the obsoletev1.0-devbranchSite structure after merge
New files
book/src/api-reference.mddocs/rust-extra.cssdocs/typedoc.jsondocs/grpc/template.htmlTest plan
book.ymlworkflow triggers and all 4 build jobs passmdbook build book)/api//api/rust/,/api/grpc/,/api/js/cargo docexcludes WASM-only crates without errors🤖 Co-authored by Claudius the Magnificent AI Agent
Summary by CodeRabbit
Documentation
Chores
Chores