Requirements & Specifications

This page lists all requirements and specifications for the sphinx-autodoc-toml project, automatically extracted from our pyproject.toml file.

Detailed Requirements:

• Core Product Features
  • Overview
  • TOML-Doc Specification
  • TOML File Parsing
  • Sphinx Integration
  • Code Quality & Linting
  • Summary
  • Planned Features
• Developer Experience Requirements
  • Overview
  • Core Principles
  • Project Structure
  • Environment Setup
  • Testing Workflow
  • Code Quality & Linting
  • Documentation
  • Build Performance
  • Packaging
  • Common Development Commands
  • Metrics & Goals
  • Summary of Requirements
  • Supporting Specifications
  • Package Publishing & Release
  • Future Improvements
  • Architecture
  • References

All Requirements

ID	Title	Status	Tags
R_DEP_001	Sphinx version MUST be 5.0 or higher for modern directive support.	open	dependencies
R_DEP_002	tomlkit MUST be used instead of tomllib to preserve comments.	open	dependencies; architecture
R_DX_001	Development environment setup MUST be simple and well-documented.	implemented	developer-experience; documentation
R_DX_002	Dependency installation SHOULD complete in under 10 seconds on average hardware.	implemented	developer-experience; performance
R_DX_003	Test suite SHOULD complete in under 30 seconds for rapid feedback.	implemented	developer-experience; performance; testing
R_DX_004	Test coverage reporting MUST be available both in terminal and HTML formats.	implemented	developer-experience; testing; quality
R_DX_005	All linting tools MUST run in parallel when possible for speed.	open	developer-experience; performance; code-quality
R_DX_006	Linting errors MUST provide clear explanations and fix suggestions.	implemented	developer-experience; code-quality
R_DX_007	Developers SHOULD be able to auto-fix most linting issues with a single command.	implemented	developer-experience; code-quality
R_DX_008	Documentation builds MUST fail on warnings to maintain quality.	open	developer-experience; documentation; quality
R_DX_009	Documentation SHOULD build in under 15 seconds for quick iteration.	open	developer-experience; performance; documentation
R_DX_010	Package builds MUST complete in under 5 seconds for rapid iteration.	implemented	developer-experience; performance; build
R_DX_011	Build errors MUST clearly indicate which file or configuration is problematic.	implemented	developer-experience; build; quality
R_DX_012	Source distributions MUST include all files needed to run tests and build docs.	implemented	developer-experience; packaging; quality
R_DX_013	Builds MUST be reproducible using locked dependency versions.	implemented	developer-experience; packaging; reproducibility
R_DX_014	Pre-commit hooks MUST run the same checks as CI to catch issues early.	implemented	developer-experience; code-quality; git; ci-cd
R_DX_015	A single command MUST set up the complete development environment.	implemented	developer-experience; setup; git-hooks
R_DX_016	The project MUST support automated publishing to PyPI on stable releases.	implemented	developer-experience; release; ci-cd; pypi
R_DX_017	Package publishing MUST use PyPI Trusted Publishing for security.	implemented	developer-experience; security; release; pypi
R_DX_018	Development versions MUST be automatically published to TestPyPI on main branch pushes.	implemented	developer-experience; testing; release; ci-cd
R_DX_019	Development version numbers MUST include commit count and hash for traceability.	implemented	developer-experience; versioning; release
R_DX_020	The publish workflow MUST run tests and linters before publishing.	implemented	developer-experience; quality; release; ci-cd
R_DX_021	Maintainers SHOULD be able to manually trigger publishing for emergency releases.	implemented	developer-experience; release; flexibility
R_DX_022	The release process MUST be fully documented for maintainers.	implemented	developer-experience; documentation; release
R_DX_023	Contributors SHOULD receive immediate feedback when their PR is published to TestPyPI.	implemented	developer-experience; testing; ci-cd; feedback
R_LINT_001	The system SHOULD provide a linter tool to validate TOML-Doc specification compliance.	planned	linter; validation; quality
R_LINT_002	The linter MUST check for Separator Rule violations.	planned	linter; validation
R_LINT_003	The linter MUST check for Attachment Rule violations.	planned	linter; validation
R_LINT_004	The linter SHOULD provide an auto-format mode to fix common issues.	planned	linter; formatting; automation
R_PARSE_001	The system MUST parse TOML files while preserving all comments and whitespace.	implemented	parser; toml
R_PARSE_002	The system MUST extract all valid doc-comments from TOML files.	implemented	parser; extraction
R_PARSE_003	The system MUST validate doc-comments against the Separator Rule.	implemented	parser; validation
R_PARSE_004	The system MUST validate doc-comments against the Attachment Rule.	implemented	parser; validation
R_PARSE_005	The system MUST support documenting both TOML table headers and key-value pairs.	implemented	parser; toml
R_PARSE_006	The system MUST support hierarchical TOML paths (e.g., project.dependencies.pytest).	implemented	parser; toml; hierarchy
R_PARSE_007	The system MUST extract the actual TOML content for documented items.	implemented	parser; extraction
R_SPEC_001	The system MUST support a doc-comment marker syntax using #: (hash-colon).	implemented	toml-doc-spec; syntax
R_SPEC_002	Doc-comment blocks MUST be preceded by at least one empty line (Separator Rule).	implemented	toml-doc-spec; validation
R_SPEC_003	Doc-comment blocks MUST NOT be separated from the item they document by any empty lines (Attachment Rule).	implemented	toml-doc-spec; validation
R_SPEC_004	Doc-comments MUST support multi-line content.	implemented	toml-doc-spec; syntax
R_SPHINX_001	The system MUST provide an autodoc-toml Sphinx directive.	implemented	sphinx; directive
R_SPHINX_002	The autodoc-toml directive MUST accept a file path as its argument.	implemented	sphinx; directive
R_SPHINX_003	The autodoc-toml directive MUST support both relative and absolute file paths.	implemented	sphinx; directive; paths
R_SPHINX_004	The system MUST generate proper Sphinx documentation nodes from doc-comments.	implemented	sphinx; generation
R_SPHINX_005	Doc-comments MUST support embedded Sphinx directives (e.g., sphinx-needs).	implemented	sphinx; directives; sphinx-needs
R_SPHINX_006	The system MUST provide clear error messages for invalid files or parsing failures.	implemented	sphinx; error-handling
R_SPHINX_007	The system MUST display TOML content alongside documentation in a collapsible format.	implemented	sphinx; ui; usability
R_TEST_001	All code MUST have test coverage of at least 80%.	open	testing; quality
R_TEST_002	All tests MUST be located in the tests/ directory.	implemented	testing
R_TEST_003	Test coverage MUST be measured and reported.	implemented	testing; quality
R_TEST_004	All tests MUST be runnable via a single 'hatch run test:run' command.	implemented	testing; tooling; developer-experience

All Specifications

ID	Title	Status	Tags
S_BUILD_001	The build backend MUST be PEP 517 compliant.	implemented	tooling
S_BUILD_002	Package installation MUST use uv for improved performance.	implemented	tooling; performance; developer-experience
S_BUILD_003	The build backend SHOULD use uv_build for optimal performance.	implemented	performance; tooling; developer-experience
S_BUILD_004	Build configuration MUST include tests in source distribution.	implemented	packaging; build
S_BUILD_005	Dependencies MUST be locked for reproducible builds across environments.	implemented	tooling; reproducibility; developer-experience
S_DOCS_001	Documentation MUST be buildable via 'hatch run docs:build' command.	implemented	documentation; tooling; developer-experience
S_DX_001	Test commands MUST provide clear, actionable output.	implemented	developer-experience; testing
S_DX_002	Code formatting MUST be automated and consistent across the project.	implemented	developer-experience; code-quality
S_DX_003	Documentation MUST demonstrate dogfooding by using autodoc-toml for its own config.	implemented	developer-experience; documentation
S_DX_004	Package layout MUST follow src-layout convention for clarity.	implemented	developer-experience; architecture; project-structure
S_DX_006	A single 'hatch run setup' command MUST configure the complete dev environment.	implemented	developer-experience; setup; git-hooks
S_EXT_001	The extension MUST provide an autodoc-toml directive for Sphinx.	implemented	sphinx; directive
S_EXT_002	The autodoc-toml directive MUST accept a file path argument.	implemented	sphinx; directive
S_EXT_003	The extension MUST resolve both relative and absolute file paths.	implemented	sphinx; paths
S_EXT_004	The extension MUST generate proper docutils nodes from doc-comments.	implemented	sphinx; generation
S_EXT_005	The extension MUST use nested_parse to support embedded Sphinx directives.	implemented	sphinx; directives
S_EXT_006	The extension MUST log clear warnings and errors for invalid files.	implemented	sphinx; error-handling
S_EXT_007	The extension MUST display TOML content in collapsible admonitions.	implemented	sphinx; ui
S_LINT_001	The linter tool MUST validate TOML-Doc specification compliance.	planned	linter; validation
S_LINT_002	Linting MUST be runnable via 'hatch run lint:all' command.	implemented	code-quality; tooling; developer-experience
S_LINT_003	The linter MUST check for Separator Rule violations.	planned	linter; validation
S_LINT_004	The linter MUST check for Attachment Rule violations.	planned	linter; validation
S_LINT_005	The linter MUST provide auto-formatting to fix spec violations.	planned	linter; formatting
S_LINT_006	The linter CLI MUST be accessible via the toml-doc-lint command.	planned
S_PARSER_001	The parser MUST recognize doc-comments marked with #: syntax.	implemented	parser; syntax
S_PARSER_002	The parser MUST validate the Separator Rule for doc-comments.	implemented	parser; validation
S_PARSER_003	The parser MUST validate the Attachment Rule for doc-comments.	implemented	parser; validation
S_PARSER_004	The parser MUST support multi-line doc-comments.	implemented	parser; syntax
S_PARSER_005	The parser MUST use tomlkit to preserve comments and whitespace.	implemented	parser; toml
S_PARSER_006	The parser MUST extract all valid doc-comments from a TOML file.	implemented	parser; extraction
S_PARSER_007	The parser MUST identify and parse TOML table headers.	implemented	parser; toml
S_PARSER_008	The parser MUST identify and parse TOML key-value pairs.	implemented	parser; toml
S_PARSER_009	The parser MUST determine hierarchical TOML paths for items.	implemented	parser; toml; hierarchy
S_PARSER_010	The parser MUST extract TOML content for documented items.	implemented	parser; extraction
S_STYLE_001	Line length MUST NOT exceed 100 characters.	implemented	code-quality
S_TYPE_001	All function definitions MUST have type annotations.	implemented	code-quality; types
S_VERSION_001	Project version MUST follow semantic versioning (semver).	implemented

All Tests

No needs passed the filters

Requirements Traceability

This diagram shows the complete traceability chain from requirements through specifications to tests:

Error

PlantUML is not available!