Core Product Features¶
This document defines the core functional requirements for the sphinx-autodoc-toml product.
Overview¶
sphinx-autodoc-toml is a Sphinx extension that enables embedding documentation directly within TOML configuration files using a special doc-comment syntax. This keeps configuration and its documentation synchronized.
TOML-Doc Specification¶
Doc-comments are distinguished from regular comments by the #: marker, allowing them to be parsed and extracted while regular # comments are ignored.
Requirement: Doc-comment blocks MUST be preceded by at least one empty line (Separator Rule). R_SPEC_002
|
The Separator Rule ensures that doc-comments are visually separated from other content, improving readability and unambiguous parsing.
Requirement: Doc-comment blocks MUST NOT be separated from the item they document by any empty lines (Attachment Rule). R_SPEC_003
|
The Attachment Rule ensures that doc-comments are clearly associated with the TOML item they document.
Multi-line doc-comments allow for comprehensive documentation of complex configuration items.
TOML File Parsing¶
Requirement: The system MUST parse TOML files while preserving all comments and whitespace. R_PARSE_001
|
Preserving comments and whitespace is essential for extracting doc-comments and validating the TOML-Doc specification rules.
Doc-comment extraction is the core functionality that enables documentation generation from TOML files.
Validation ensures that only properly formatted doc-comments are extracted and processed.
Attachment validation ensures that doc-comments are correctly associated with their TOML items.
Requirement: The system MUST support documenting both TOML table headers and key-value pairs. R_PARSE_005
|
Both table headers (e.g., [project]) and individual keys (e.g., name = "value") can have doc-comments.
Requirement: The system MUST support hierarchical TOML paths (e.g., project.dependencies.pytest). R_PARSE_006
|
Hierarchical path support allows for documenting nested TOML structures.
Extracting TOML content alongside documentation enables comprehensive output that shows both the documentation and the configuration being documented.
Sphinx Integration¶
The directive is the primary interface for including TOML documentation in Sphinx projects.
File paths can be relative to the source directory or absolute.
Requirement: The autodoc-toml directive MUST support both relative and absolute file paths. R_SPHINX_003
|
Flexible path resolution makes the directive easy to use in various documentation structures.
Requirement: The system MUST generate proper Sphinx documentation nodes from doc-comments. R_SPHINX_004
|
Generated nodes integrate seamlessly with Sphinx’s documentation building process.
Requirement: Doc-comments MUST support embedded Sphinx directives (e.g., sphinx-needs). R_SPHINX_005
|
This enables powerful documentation features like requirements traceability directly in TOML files.
Requirement: The system MUST provide clear error messages for invalid files or parsing failures. R_SPHINX_006
|
Clear error messages help users quickly identify and fix issues with their TOML documentation.
Requirement: The system MUST display TOML content alongside documentation in a collapsible format. R_SPHINX_007
|
Collapsible display keeps documentation clean while allowing users to view the actual configuration when needed.
Code Quality & Linting¶
Requirement: The system SHOULD provide a linter tool to validate TOML-Doc specification compliance. R_LINT_001
|
A linter helps users ensure their TOML files comply with the TOML-Doc specification before building documentation.
Detecting separator rule violations helps users write properly formatted doc-comments.
Detecting attachment rule violations ensures doc-comments are properly associated with TOML items.
Auto-formatting reduces manual work and helps maintain consistent TOML-Doc formatting across files.
Summary¶
These requirements define the core functionality of sphinx-autodoc-toml:
Planned Features¶
Features planned for future implementation:
