How do I configure Read the Docs to use sphinx-autodoc-annotatio

ghz 昨天 ⋅ 2 views

How do I configure Read the Docs to use sphinx-autodoc-annotation?

Answer

To configure Read the Docs (RTD) to use sphinx-autodoc-annotation in your Sphinx documentation, you need to make a few adjustments to your Sphinx project configuration and ensure the appropriate dependencies are installed. Here's how you can set it up:

1. Install sphinx-autodoc-annotation

First, you need to install the sphinx-autodoc-annotation extension in your project. This extension allows Sphinx to automatically include type annotations in your generated documentation.

Locally:

You can install the extension using pip:

pip install sphinx-autodoc-annotation

On Read the Docs:

Read the Docs uses requirements.txt or setup.py to install dependencies. To make sure the extension is installed on Read the Docs, you need to add it to the requirements.txt file (if you have one) or your setup.py.

In requirements.txt:

sphinx-autodoc-annotation

2. Enable the Extension in conf.py

After installing the extension, you'll need to enable it in your Sphinx project's configuration file (conf.py).

In your conf.py, add 'sphinx_autodoc_annotation' to the extensions list:

# conf.py

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

3. Configure the Extension (Optional)

By default, sphinx-autodoc-annotation will automatically use type annotations in function signatures for autodoc. However, you can customize its behavior through additional configuration options.

For example, you can change how the type annotations are displayed. To configure this, add the following options to conf.py:

# conf.py

# This will configure the extension to display type annotations
autodoc_typehints = 'description'  # Options: 'none', 'signature', 'description'
  • 'none': No type hints are shown.
  • 'signature': Type hints are shown in the function signature.
  • 'description': Type hints are shown in the function's description.

4. Push Changes to Read the Docs

Once you have updated your requirements.txt (or setup.py) and conf.py, commit these changes to your version control system (e.g., Git), and push them to the repository connected to Read the Docs.

Read the Docs will automatically install the dependencies listed in requirements.txt and rebuild your documentation, including the use of sphinx-autodoc-annotation.

5. Verify the Changes

After your documentation is rebuilt on Read the Docs, check the generated documentation to ensure that type annotations are being correctly displayed according to your configuration.

This setup will enable sphinx-autodoc-annotation to automatically integrate type annotations into your Sphinx documentation on Read the Docs.

#py