Skip to content

Document Rust applications and publish versioned SDK reference - #8422

Open
Amaury Chamayou (achamayou) wants to merge 1 commit into
achamayou-rust-interface-explorationfrom
achamayou-cautious-system
Open

Amaury Chamayou (achamayou) wants to merge 1 commit into
achamayou-rust-interface-explorationfrom
achamayou-cautious-system

Conversation

@achamayou

Copy link
Copy Markdown
Member

Motivation

Stacked on #8200, targeting achamayou-rust-interface-exploration.

Rust application authors need a runnable path from CCF setup to authenticated requests, and API contracts comparable in quality to the existing C++ documentation. The initial Rust guide describes the interface but does not provide a source-backed walkthrough or generated API reference.

Implementation summary

  • Expand the existing guide with sample-backed Cargo/CMake and handler snippets, source-tree and installed-SDK instructions, sandbox requests, expected responses, and explicit experimental/capability limits.
  • Document the safe SDK's ownership, authentication, transaction, error and serialization contracts. Add executable and compile-fail doctests, deny missing documentation and broken intra-doc links, and hide ABI implementation details without removing exported symbols.
  • Generate native rustdoc alongside each Sphinx documentation version, following the existing TypeDoc model. Build only the dependency-free application SDK, copy its complete output, and validate generated page/anchor links, including cached doctrees. Older versions without the SDK skip generation; SDK generation failures are fatal.

Local validation passed: the full warnings-as-errors Sphinx build, 10 documentation-helper tests, SDK unit tests and doctests on Rust 1.90.0 and 1.93.1, sample cargo check, and scripts/ci-checks.sh. The native Debug basic_rust target also builds, and the ccf_app_rust_test and e2e_basic_rust CTest selections pass. The helper tests are wired into the existing documentation CI step; SDK doctests use the existing Rust test registration.

Safety and compatibility

No application or bridge runtime behavior, ABI, ledger encoding, consensus, recovery, or mixed-version behavior changes. Rust edits add documentation, doctests, documentation lints and documentation-only visibility attributes; sample edits add snippet markers.

Rust documentation generation does not build a CCF executable. SKIP_RUSTDOC is an explicit local-preview escape hatch, not used in publishing or CI. Native rustdoc retains its own presentation and search; Sphinx remains the versioned entry point and conceptual guide.

Add a source-backed tutorial, public SDK contracts and doctests, and SDK-only rustdoc generation integrated with CCF's versioned Sphinx documentation. Validate generated API links and document the experimental interface's limits.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant