[Roadmap] Automated API documentation pipeline for Qumat and QDP

[viiccwen]

GSoC 2026 — Automated API Documentation Pipeline

Scope: qumat, qumat_qdp, qdp-core, Docusaurus website, docs CI

Goal: Generate Python and Rust API references directly from source code and publish them under a unified Docusaurus API Reference section, with CI validation, local developer commands, and release/tag-based versioning.

Related umbrella issue: #1012

---

Track A — Public API audit

Establish the public API boundary and documentation conventions before building the generator.

ID	Issue	What to do	Week
A1	#1336 [Docs] Add missing QDP Python API docstrings	Audit public qumat / qumat_qdp APIs and identify public APIs with missing docstrings.	Week 1
A2	#1337 [Docs] Refresh QDP Python API docstrings	Review existing public API docstrings, identify stale or insufficient descriptions, and define/align the docstring convention for follow-up implementation.	Week 1

• [Docs] Add missing QDP Python API docstrings #1336
• [Docs] Refresh QDP Python API docstrings #1337

---

Track B — Python API documentation pipeline

Build the pydoc-markdown-based Python API reference pipeline and generate Docusaurus-compatible Markdown in reviewable stages.

ID	Issue	What to do	Week
B1	#1346 [feature] Add pydoc-markdown foundation for Python API docs	Set up pydoc-markdown with Markdown output; configure autodoc and type hints; add a local make docs-python entry point; produce the first end-to-end Python API build under docs/api/python/.	Week 2
B2	#1347 [feature] Generate Python API pages from public module discovery	Discover public modules automatically; generate pydoc-markdown stubs and module lists; enforce one-module-per-page output for the Python API reference.	Week 3
B3	#1348 [Docs] Add source docstrings for QDP constructor and alias API entries	Post-process generated Markdown where needed, including long signatures and formatting that affects Docusaurus readability, without changing the documented API surface.	Week 3

• [feature] Add pydoc-markdown foundation for Python API docs #1346
• [feature] Generate Python API pages from public module discovery #1347
• [Docs] Add source docstrings for QDP constructor and alias API entries #1348
• [docs] Define QDP Python public API surface for generated docs #1382

---

Track C — Rust API documentation pipeline

Convert Rust API docs from rustdoc comments into website-ready Markdown without making CUDA/GPU availability a hard requirement.

ID	Issue	What to do	Week
C1	#1349 [feature] Plan Rust API surface and rustdoc conversion path	Review the Rust API surface starting with qdp-core; define published crates/modules; validate rustdoc JSON and rustdoc-md feasibility; document how the workflow should behave when CUDA or nightly rustdoc tooling is unavailable.	Week 4
C2	#1350 [feature] Generate Rust API Markdown for Docusaurus	Implement the Rust API doc generation script and package list; post-process Markdown for Docusaurus; add a local make docs-rust entry point; output generated docs to docs/api/rust/.	Week 5

• [feature] Plan Rust API surface and rustdoc conversion path #1349
• [feature] Generate Rust API Markdown for Docusaurus #1350

---

Track D — Website integration

Publish Python and Rust API references under one Docusaurus API section with generated navigation.

ID	Issue	What to do	Week
D1	#1351 [feature] Add unified API Reference section to the website	Add an API Reference landing page and integrate the generated Python/Rust API docs into the Docusaurus docs structure with a consistent top-level entry point.	Week 6
D2	#1352 [feature] Generate Docusaurus API sidebars from Python and Rust doc outputs	Add a website-side sidebar generation script; wire it into local website build/start commands; provide graceful fallback behavior when generated API outputs do not exist yet.	Week 6

• [feature] Add unified API Reference section to the website #1351
• [feature] Generate Docusaurus API sidebars from Python and Rust doc outputs #1352

---

Track E — CI, previews, and versioning

Keep API docs reproducible for contributors and releases, while separating low-risk validation from higher-risk workflows that require write or deploy permissions.

ID	Issue	What to do	Week
E1	#1353 [ci] Add API docs build validation workflow	Add a GitHub Actions workflow that installs docs dependencies, runs the Python API docs build, runs the Rust API docs build where supported, and validates the Docusaurus website build. Keep this workflow read-only and focused on validation.	Week 7
E2	#1354 [ci] Upload API docs preview artifacts for pull requests	Upload generated API docs / website preview artifacts for PR review, with API-related path filters. Avoid branch pushes or deploy permissions in the first preview iteration.	Week 7
E3	#1355 [feature] Add local docs versioning command for release validation	Add a local command/script for generating versioned docs from a supplied version string, so release documentation can be tested before enabling tag automation.	Week 8
E4	#1356 [ci] Generate versioned API docs from release tags	Add a tag-triggered workflow for versioned API documentation after the local versioning flow and ASF deployment/write-back policy are agreed. Keep permissions and generated-file write-back behavior explicit for review.	Week 8

• [ci] Add API docs build validation workflow #1353
• [ci] Upload API docs preview artifacts for pull requests #1354
• [feature] Add local docs versioning command for release validation #1355
• [ci] Generate versioned API docs from release tags #1356

---

Track F — UX iteration, hardening, and contributor docs

Use feedback to refine the generated docs and make the workflow maintainable after GSoC.

ID	Issue	What to do	Week
F1	#1357 [docs] Iterate on API docs UX with user feedback	Collect feedback from ML practitioners, quant traders, and contributors; evaluate usability/navigation; iterate on structure and wording.	Week 9
F2	#1358 [feature] Polish and harden the API documentation pipeline	Improve consistency across Python and Rust docs; handle edge cases and error states; address mentor feedback.	Week 10
F3	#1359 [docs] Document the API docs contributor workflow	Write contributor guide for building, previewing, versioning, and troubleshooting API docs.	Week 11
F4	#1360 [docs] Final validation, demo, and report for API docs pipeline	Reserve buffer for unexpected issues; validate final goals; prepare final report and demo.	Week 12

• [docs] Iterate on API docs UX with user feedback #1357
• [feature] Polish and harden the API documentation pipeline #1358
• [docs] Document the API docs contributor workflow #1359
• [docs] Final validation, demo, and report for API docs pipeline #1360

---