Analyze Generation of Detailed Design Documents from Rust Code Using Sphinx-Based Docs-as-Code Approach

[dcalavrezo-qorix]

Goal:

Evaluate options for automatically generating detailed design documents from Rust code within our current docs-as-code structure

Scope

-Assess how well available Sphinx extensions for Rust can support detailed design-level documentation.

• Compare sphinxcontrib-rust and sphinx-rust in terms of features, integration, stability and compatibility with our toolchain.

[dcalavrezo-qorix]

Assessment: Using sphinxcontrib-rust for Rust API Documentation in S-Core

Context

We explored generating detailed design/API documentation for Rust code within our Sphinx-based docs-as-code setup.
We switched to sphinxcontrib-rust, as implemented in PR #27.

---

Changes from PR #27

• Added the use of extension sphinxcontrib-rust.
• Updated the conf.py and documentation sources to use sphinxcontrib-rust directives and roles.
• Ensured compatibility with modern Sphinx versions (>=8.x), as sphinxcontrib-rust does not limit Sphinx versioning.
• Successfully generated Rust API documentation with cross-referencing, without encountering build errors or issues from previous attempts.

---

Advantages of sphinxcontrib-rust

• Sphinx version compatibility:
  Works with Sphinx 8.x and likely newer versions (no strict pinning to old Sphinx releases).

• Simple setup:
  The extension is lightweight and easy to configure—just add to conf.py and use reStructuredText roles/directives (e.g., :rust:mod:, :rust:struct:).

• Direct cross-referencing:
  Supports inline references to Rust modules, structs, enums, traits, etc., improving navigation in generated docs.

• Works with modern Rust:
  No issues with parsing current Rust crate layouts or TOML files, as seen with other plugins.

---

Limitations of sphinxcontrib-rust

• No sphinx-needs integration:
  Does not automatically create or link needs objects for traceability or requirements management.

  • Any mapping between Rust code and requirements/design objects must be done manually.

• Limited automation:
  The extension primarily focuses on referencing Rust items; it does not generate detailed API listings or docstrings out-of-the-box (compared to full-featured autodoc tools in Python).

• Manual effort for requirements traceability:
  Users need to manually create and maintain links between code and requirements.

---

Conclusion

sphinxcontrib-rust provides a stable and straightforward solution for integrating Rust code documentation into Sphinx, at the cost of manual effort for traceability.
It is a pragmatic choice for current and future Sphinx versions, especially if API documentation and requirements links are not required to be automated.

---

See PR #27 for the exact implementation details.

[dcalavrezo-qorix]

The DDD example can be seen here: https://eclipse-score.github.io/inc_mw_per/pr-27/ddd.html

[dcalavrezo-qorix]

Assessment: Using sphinx-rust for Rust API Documentation in Sphinx

Context

We evaluated sphinx-rust to automatically generate and cross-reference Rust API documentation inside our Sphinx-based docs-as-code system.

---

Advantages of sphinx-rust

• sphinx-needs Integration:
  The main feature: sphinx-rust can directly generate needs objects (e.g., design or requirement traceability items) from Rust code documentation.

  • This enables end-to-end traceability, linking code artifacts to design/requirements in the same documentation set.

• Automatic API extraction:
  Can extract API-level documentation (structs, enums, traits, functions) directly from Rust code using rustdoc or similar introspection.

  • Reduces manual effort and risk of docs getting out-of-sync with code.

• Cross-referencing:
  Supports Sphinx roles/directives for Rust items, allowing easy inline references and links throughout your documentation.

---

Limitations and Downsides

• Outdated Sphinx version requirement:
  Currently limited to Sphinx 7.x (sphinx~=7.3 in its dependencies).

  • Not compatible with modern Sphinx (8.x+) as of July 2025.
  • Blocks use in new Sphinx projects unless updated by maintainers.

• TOML/workspace limitations:
  The extension's TOML parser does not support Cargo workspace versioning or inheritance (e.g., version.workspace = true).

  • Fails to parse modern multi-crate Rust project layouts.

• Path object errors:
  Errors arise in some environments due to incompatible usage of Path/StrPath objects with docutils, especially with Sphinx parallel builds.

  • Causes build failures with cryptic Python errors.

• Maintenance:
  No evidence of recent updates for Sphinx 8.x compatibility or for modern Cargo workspaces.

  • May require forking or significant upstream contribution to use in active, modern documentation pipelines.

---

Comparison to sphinxcontrib-rust

• sphinxcontrib-rust:

  • More limited feature set (no needs objects).
  • Compatible with new Sphinx versions and modern Rust layouts.

• sphinx-rust:

  • More feature-rich (traceability, autodoc, needs integration).
  • Currently unusable in up-to-date environments unless the above limitations are addressed.

---

Conclusion

sphinx-rust has significant advantages for projects needing automated traceability and requirements linking, due to its sphinx-needs integration and rich API extraction.

However, practical use is blocked by:

• Sphinx version pinning (~=7.3)
• Lack of workspace TOML support
• Path handling bugs in modern Sphinx/docutils

Action needed:
The plugin would need to be actively maintained and updated to support:

• Sphinx 8.x+
• Modern Cargo workspace TOML structures
• Path handling with latest docutils

Until these changes are made, alternative solutions (like sphinxcontrib-rust) should be used for stability and compatibility.

---