Installation

This guide covers installing and setting up sphinx-autodoc-toml for use in your Sphinx documentation projects.

Requirements

  • Python 3.8 or higher

  • Sphinx 5.0 or higher

Installation from PyPI

Install the latest stable release from PyPI:

pip install sphinx-autodoc-toml

Or with uv (recommended for faster installation):

uv pip install sphinx-autodoc-toml

Installation from Source

For development or to use the latest unreleased features:

git clone https://github.com/calvingiles/autodoc-toml.git
cd autodoc-toml
pip install -e .

Testing Development Versions

Development versions are automatically published to TestPyPI on every commit to the main branch.

To install a development version:

pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ sphinx-autodoc-toml

Note: Development versions use the format {version}.dev{count}+{hash} (e.g., 0.1.0.dev42+a1b2c3d).

Sphinx Configuration

After installation, enable the extension in your Sphinx conf.py:

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

Optional: If you’re using sphinx-needs for requirements tracking, add it as well:

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

Verifying Installation

To verify the extension is installed correctly:

# In a Python shell or script
import sphinx_autodoc_toml
print(f"sphinx-autodoc-toml version: {sphinx_autodoc_toml.__version__}")

Or check that Sphinx recognizes the extension:

# In your docs directory
sphinx-build --version
# Then try building your docs

Next Steps

Troubleshooting

Extension Not Found

If you see an error like Extension error: Could not import extension sphinx_autodoc_toml:

  1. Verify the package is installed: pip list | grep sphinx-autodoc-toml

  2. Ensure you’re using the correct Python environment

  3. Try reinstalling: pip install --force-reinstall sphinx-autodoc-toml

Import Errors

If you encounter import errors, verify your dependencies:

pip install --upgrade sphinx>=5.0 tomlkit>=0.11.0

For additional help, please file an issue on GitHub.