API Reference
This page documents the Python API for sphinx-autodoc-toml.
Parser Module
Core parser for extracting doc-comments from TOML files.
Specification: The parser MUST recognize doc-comments marked with #: syntax. S_PARSER_001
|
|
|
|
Specification: The parser MUST validate the Separator Rule for doc-comments. S_PARSER_002
|
|
|
|
Specification: The parser MUST validate the Attachment Rule for doc-comments. S_PARSER_003
|
|
|
|
Specification: The parser MUST support multi-line doc-comments. S_PARSER_004
|
|
|
|
Specification: The parser MUST use tomlkit to preserve comments and whitespace. S_PARSER_005
|
|
|
|
Specification: The parser MUST extract all valid doc-comments from a TOML file. S_PARSER_006
|
|
|
|
Specification: The parser MUST identify and parse TOML table headers. S_PARSER_007
|
|
|
|
Specification: The parser MUST identify and parse TOML key-value pairs. S_PARSER_008
|
|
|
|
Specification: The parser MUST determine hierarchical TOML paths for items. S_PARSER_009
|
|
|
|
Specification: The parser MUST extract TOML content for documented items. S_PARSER_010
|
|
|
|
Bases: object
Represents a doc-comment block extracted from a TOML file.
Return the full dotted path (e.g., ‘project.dependencies’).
Return the TOML table notation (e.g., ‘[project.dependencies]’).
-
class sphinx_autodoc_toml.parser.TomlDocParser(toml_path: Path)[source]
Bases: object
Parser for extracting doc-comments from TOML files according to TOML-Doc spec.
-
KEY_PATTERN = re.compile('^([a-zA-Z0-9_-]+)\\s*=')
-
TABLE_PATTERN = re.compile('^\\[([^\\]]+)\\]')
-
parse() → List[DocComment][source]
Parse the TOML file and extract all valid doc-comments.
- Returns:
List of DocComment objects
-
sphinx_autodoc_toml.parser.parse_toml_file(toml_path: Path) → List[DocComment][source]
Parse a TOML file and extract all doc-comments.
- Parameters:
toml_path – Path to the TOML file
- Returns:
List of DocComment objects
Example
>>> from pathlib import Path
>>> doc_comments = parse_toml_file(Path("pyproject.toml"))
>>> for dc in doc_comments:
... print(f"{dc.toml_path}: {dc.content}")
Extension Module
Sphinx extension for autodoc-toml directive.
Specification: The extension MUST provide an autodoc-toml directive for Sphinx. S_EXT_001
|
|
|
|
Specification: The autodoc-toml directive MUST accept a file path argument. S_EXT_002
|
|
|
|
Specification: The extension MUST resolve both relative and absolute file paths. S_EXT_003
|
|
|
|
Specification: The extension MUST generate proper docutils nodes from doc-comments. S_EXT_004
|
|
|
|
Specification: The extension MUST use nested_parse to support embedded Sphinx directives. S_EXT_005
|
|
|
|
Specification: The extension MUST log clear warnings and errors for invalid files. S_EXT_006
|
|
|
|
Specification: The extension MUST display TOML content in collapsible admonitions. S_EXT_007
|
|
|
|
-
class sphinx_autodoc_toml.extension.AutodocTomlDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]
Bases: Directive
Directive to automatically document TOML files with embedded doc-comments.
- Usage:
-
final_argument_whitespace = True
May the final argument contain whitespace?
-
has_content = False
May the directive have content?
-
option_spec = {'recursive': <function flag>, 'show-all': <function flag>}
Mapping of option names to validator functions.
-
optional_arguments = 0
Number of optional arguments after the required arguments.
-
required_arguments = 1
Number of required directive arguments.
-
run() → List[Node][source]
Execute the directive.
- Returns:
List of docutils nodes to insert into the document
-
sphinx_autodoc_toml.extension.setup(app: Sphinx) → Dict[str, Any][source]
Sphinx extension setup function.
- Parameters:
app – The Sphinx application instance
- Returns:
Extension metadata
Linter Module
Linter and formatter for TOML-Doc specification compliance.
Specification: The linter tool MUST validate TOML-Doc specification compliance. S_LINT_001
|
|
|
|
Specification: The linter MUST check for Separator Rule violations. S_LINT_003
|
|
|
|
Specification: The linter MUST check for Attachment Rule violations. S_LINT_004
|
|
|
|
Specification: The linter MUST provide auto-formatting to fix spec violations. S_LINT_005
|
|
|
|
-
class sphinx_autodoc_toml.linter.LintError(line: int, message: str, severity: str = 'error')[source]
Bases: object
Represents a linting error in a TOML file.
-
class sphinx_autodoc_toml.linter.TomlDocLinter(toml_path: Path)[source]
Bases: object
Linter for TOML-Doc specification compliance.
-
format() → str[source]
Format the TOML file to comply with TOML-Doc specification.
- Returns:
Formatted TOML content
-
lint() → List[LintError][source]
Lint the TOML file for TOML-Doc specification compliance.
- Returns:
List of LintError objects
-
sphinx_autodoc_toml.linter.main() → int[source]
Main entry point for the toml-doc-lint CLI tool.
