{"id":7739,"library":"sphinx-automodapi","title":"Sphinx AutoModAPI","description":"Sphinx AutoModAPI is an extension for Sphinx that simplifies the automatic generation of API documentation for entire Python modules and packages. It integrates with Sphinx's autodoc and autosummary to create comprehensive API reference pages and summary tables. The current version is 0.22.0, and it maintains a regular release cadence, often aligning with new Python and Sphinx versions.","status":"active","version":"0.22.0","language":"en","source_language":"en","source_url":"https://github.com/astropy/sphinx-automodapi","tags":["sphinx","documentation","autodoc","api_generation","astropy"],"install":[{"cmd":"pip install sphinx-automodapi","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core documentation generation framework that this extension builds upon.","package":"Sphinx"}],"imports":[{"note":"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.","wrong":"import sphinx_automodapi","symbol":"automodapi extension","correct":"extensions = ['sphinx.ext.autodoc', 'sphinx_automodapi.automodapi']"}],"quickstart":{"code":"import os\nimport shutil\n\n# 1. Create dummy package structure\npackage_dir = 'my_package'\ndocs_dir = 'docs'\n\nshutil.rmtree(docs_dir, ignore_errors=True)\nshutil.rmtree(package_dir, ignore_errors=True)\n\nos.makedirs(os.path.join(package_dir, 'submodule'), exist_ok=True)\nos.makedirs(docs_dir, exist_ok=True)\n\n# 2. Create a dummy Python module for documentation\nwith open(os.path.join(package_dir, '__init__.py'), 'w') as f: f.write('')\nwith open(os.path.join(package_dir, 'my_module.py'), 'w') as f:\n    f.write('''\ndef my_function(arg1, arg2):\n    \"\"\"A sample function.\n\n    :param arg1: First argument.\n    :param arg2: Second argument.\n    :return: The sum of arg1 and arg2.\n    \"\"\"\n    return arg1 + arg2\n\nclass MyClass:\n    \"\"\"A sample class.\n\n    :param name: The name for the class instance.\n    \"\"\"\n    def __init__(self, name):\n        self.name = name\n\n    def greet(self):\n        \"\"\"Greets the user.\n        \"\"\"\n        return f\"Hello, {self.name}!\"\n''')\n\n# 3. Create Sphinx conf.py\nwith open(os.path.join(docs_dir, 'conf.py'), 'w') as f:\n    f.write(f'''\nimport os\nimport sys\nsys.path.insert(0, os.path.abspath('..')) # Add parent directory to path for module discovery\n\nproject = 'My Awesome Project'\ncopyright = '2023, Your Name'\nextensions = [\n    'sphinx.ext.autodoc',\n    'sphinx.ext.napoleon', # Recommended for Google/NumPy style docstrings\n    'sphinx_automodapi.automodapi',\n    'sphinx_automodapi.automodsumm' # For generating summary tables\n]\nhtml_theme = 'alabaster'\n\n# REQUIRED for sphinx-automodapi\nautomodapi_toctreedir = '_autosummary'\n''')\n\n# 4. Create an RST file to use automodapi\nwith open(os.path.join(docs_dir, 'index.rst'), 'w') as f:\n    f.write(f'''\n.. automodapi:: my_package.my_module\n   :no-inherited-members:\n\n.. toctree::\n   :maxdepth: 2\n   :caption: Contents:\n\n   _autosummary/my_package.my_module\n''')\n\nprint(\"Setup complete!\\n\")\nprint(\"To build the documentation:\\n\")\nprint(f\"1. Navigate to the '{docs_dir}' directory: cd {docs_dir}\")\nprint(\"2. Run Sphinx build command: sphinx-build -b html . _build\")\nprint(\"3. Open _build/index.html in your browser.\")\nprint(\"Note: You need Sphinx installed (pip install sphinx) to run sphinx-build.\")\n","lang":"python","description":"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."},"warnings":[{"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).","message":"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.","severity":"breaking","affected_versions":">=0.17.0"},{"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.","message":"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.","severity":"breaking","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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 .`).","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Install the package: `pip install sphinx-automodapi`.","cause":"The `sphinx-automodapi` package is not installed in the Python environment where Sphinx is being executed.","error":"Extension error: Could not import extension sphinx_automodapi.automodapi (exception: No module named 'sphinx_automodapi')"},{"fix":"Verify that your `conf.py` contains `extensions = [..., 'sphinx_automodapi.automodapi', ...]` (or the shorter `'automodapi'` if using the simple form) in the `extensions` list.","cause":"The extension name is misspelled, or `sphinx_automodapi.automodapi` was not correctly added to the `extensions` list in your `conf.py`.","error":"Sphinx error: Unknown extension 'automodapi'"},{"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('../'))`.","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`.","error":"WARNING: don't know which module to document for u'my_package.my_module'"},{"fix":"Add `automodapi_toctreedir = '_autosummary'` (or your preferred directory name) to your `conf.py` file.","cause":"The `automodapi_toctreedir` configuration option, which specifies where generated API pages should be placed, is required but was not defined in `conf.py`.","error":"RuntimeError: automodapi_toctreedir configuration option must be set for automodapi to work correctly"}]}