Sphinx AutoModAPI

Common errors

• Extension error: Could not import extension sphinx_automodapi.automodapi (exception: No module named 'sphinx_automodapi')

  cause The `sphinx-automodapi` package is not installed in the Python environment where Sphinx is being executed.
  fix Install the package: `pip install sphinx-automodapi`.

• Sphinx error: Unknown extension 'automodapi'

  cause The extension name is misspelled, or `sphinx_automodapi.automodapi` was not correctly added to the `extensions` list in your `conf.py`.
  fix Verify that your `conf.py` contains `extensions = [..., 'sphinx_automodapi.automodapi', ...]` (or the shorter `'automodapi'` if using the simple form) in the `extensions` list.

• WARNING: don't know which module to document for u'my_package.my_module'

  cause Sphinx's autodoc cannot find or import the specified Python module. This typically means the module's parent directory is not on Python's `sys.path`.
  fix In your `docs/conf.py`, add the path to your package's root to `sys.path`. For example: `import os; import sys; sys.path.insert(0, os.path.abspath('../'))`.

• RuntimeError: automodapi_toctreedir configuration option must be set for automodapi to work correctly

  cause The `automodapi_toctreedir` configuration option, which specifies where generated API pages should be placed, is required but was not defined in `conf.py`.
  fix Add `automodapi_toctreedir = '_autosummary'` (or your preferred directory name) to your `conf.py` file.

Warnings

• breaking Support for older Python versions is regularly dropped. As of v0.22.0, Python 3.9 and older are no longer supported, with previous versions dropping 3.8 and 3.7.
  Fix: Upgrade your Python environment to 3.10 or newer, or pin `sphinx-automodapi` to an older version compatible with your current Python environment (e.g., `sphinx-automodapi<0.22` for Python 3.9).
• breaking While `sphinx-automodapi` strives for compatibility with new Sphinx versions, older `sphinx-automodapi` versions may not work with the latest Sphinx, and vice-versa. For example, v0.22.0 introduced Sphinx 9 compatibility, potentially breaking older setups.
  Fix: Ensure `sphinx-automodapi` and `Sphinx` versions are compatible. Consult the changelog or testing matrix in the project's GitHub repository for specific version requirements, or update both to their latest compatible versions.
• gotcha Confusing `sphinx_automodapi.automodapi` (generates full API documentation pages for modules/classes) with `sphinx_automodapi.automodsumm` (generates summary tables of members within an existing RST file) is common. They are distinct extensions with different use cases.
  Fix: Use `sphinx_automodapi.automodapi` to create dedicated API pages. Use `sphinx_automodapi.automodsumm` to embed compact, sortable tables of functions, classes, or attributes into other documentation pages.
• gotcha Sphinx needs to be able to import the Python modules you are trying to document. If your package is not installed or its root directory is not included in Python's `sys.path` when Sphinx runs, autodoc (and thus automodapi) will fail to find it.
  Fix: In your `docs/conf.py`, add the path to your package's root directory to `sys.path`. A common pattern is `sys.path.insert(0, os.path.abspath('../'))` if `conf.py` is in the `docs` folder next to your package. Alternatively, install your package in editable mode (`pip install -e .`).

Install

• pip install sphinx-automodapi Install latest version

Imports

• automodapi extension
  wrong:

  import sphinx_automodapi

  correct:

  extensions = ['sphinx.ext.autodoc', 'sphinx_automodapi.automodapi']

  sphinx-automodapi is a Sphinx extension, not a Python library meant for direct import and symbol usage in application code. It's loaded via the 'extensions' list in Sphinx's conf.py.

Quickstart

This quickstart code creates a minimal Python package and a Sphinx documentation project. It configures `conf.py` to enable `sphinx_automodapi.automodapi` and `sphinx_automodapi.automodsumm`, and creates an `index.rst` file that uses `automodapi` to document `my_package.my_module`. Run this Python script, then navigate into the `docs` directory and use `sphinx-build` to generate the HTML documentation.

import os
import shutil

# 1. Create dummy package structure
package_dir = 'my_package'
docs_dir = 'docs'

shutil.rmtree(docs_dir, ignore_errors=True)
shutil.rmtree(package_dir, ignore_errors=True)

os.makedirs(os.path.join(package_dir, 'submodule'), exist_ok=True)
os.makedirs(docs_dir, exist_ok=True)

# 2. Create a dummy Python module for documentation
with open(os.path.join(package_dir, '__init__.py'), 'w') as f: f.write('')
with open(os.path.join(package_dir, 'my_module.py'), 'w') as f:
    f.write('''
def my_function(arg1, arg2):
    """A sample function.

    :param arg1: First argument.
    :param arg2: Second argument.
    :return: The sum of arg1 and arg2.
    """
    return arg1 + arg2

class MyClass:
    """A sample class.

    :param name: The name for the class instance.
    """
    def __init__(self, name):
        self.name = name

    def greet(self):
        """Greets the user.
        """
        return f"Hello, {self.name}!"
''')

# 3. Create Sphinx conf.py
with open(os.path.join(docs_dir, 'conf.py'), 'w') as f:
    f.write(f'''
import os
import sys
sys.path.insert(0, os.path.abspath('..')) # Add parent directory to path for module discovery

project = 'My Awesome Project'
copyright = '2023, Your Name'
extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.napoleon', # Recommended for Google/NumPy style docstrings
    'sphinx_automodapi.automodapi',
    'sphinx_automodapi.automodsumm' # For generating summary tables
]
html_theme = 'alabaster'

# REQUIRED for sphinx-automodapi
automodapi_toctreedir = '_autosummary'
''')

# 4. Create an RST file to use automodapi
with open(os.path.join(docs_dir, 'index.rst'), 'w') as f:
    f.write(f'''
.. automodapi:: my_package.my_module
   :no-inherited-members:

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   _autosummary/my_package.my_module
''')

print("Setup complete!\n")
print("To build the documentation:\n")
print(f"1. Navigate to the '{docs_dir}' directory: cd {docs_dir}")
print("2. Run Sphinx build command: sphinx-build -b html . _build")
print("3. Open _build/index.html in your browser.")
print("Note: You need Sphinx installed (pip install sphinx) to run sphinx-build.")