Quick Start

Installation

Install sphinx-autodoc-toml using pip:

pip install sphinx-autodoc-toml

Configuration

Add the extension to your Sphinx conf.py:

extensions = [
    'sphinx_autodoc_toml',
    # ... other extensions
]

For requirements tracking, also add sphinx-needs:

extensions = [
    'sphinx_autodoc_toml',
    'sphinx_needs',
    # ... other extensions
]

Usage

Basic Example

  1. Add doc-comments to your TOML file:

    [project]
name = "my-project"
version = "1.0.0"

#: This section defines the project dependencies.
#: All dependencies should be pinned to specific versions.
[project.dependencies]
requests = "==2.31.0"

  2. In your .rst documentation file, use the autodoc-toml directive:

    .. autodoc-toml:: ../pyproject.toml

  3. Build your documentation:

    sphinx-build -b html docs docs/_build/html

With Requirements Tracking

You can embed sphinx-needs directives in your doc-comments:

#: Documentation for the project dependencies.
#:
#: .. req:: All dependencies MUST be pinned to specific versions.
#:    :id: R_DEPS_001
#:    :status: open
#:    :tags: security
[project.dependencies]
requests = "==2.31.0"

When Sphinx builds your documentation, the .. req:: directive will be processed by sphinx-needs, creating a trackable requirement that appears in your documentation.

Next Steps