Quickstart#

This section describes how to get started with sphinx-autodoc2 🎉

Installation#

Install from PyPI:

pip install sphinx-autodoc2

Enabling the extension#

Add autodoc2 to the extensions list in your conf.py file and, as as a minimum, set the autodoc2_packages configuration option to the list of packages you want to document:

extensions = [
    "autodoc2",
]
autodoc2_packages = [
    "../my_package",
]

This will generate documentation for the my_package package, and all of its sub-packages and modules, within the apidocs (or autodoc2_output_dir) directory, which you can include in a toctree directive.

.. toctree::
   :maxdepth: 2

   apidocs/index

Manually documenting select objects#

sphinx-autodoc2 can be used in one or both of two “modes”:

auto mode (default) - Automatically generate files for all modules and packages specified by the autodoc2_packages configuration option.
manual mode - Use the autodoc2-object directive to manually specify which objects to document.

To turn off auto mode, set the autodoc2_packages[auto_mode] configuration option to False:

extensions = [
    "autodoc2",
]
autodoc2_packages = [
    {
        "path": "../my_package",
        "auto_mode": False,
    },
]

You can even render only the docstring of any object, see: autodoc2-docstring directive.

Ignoring autodoc2 warnings#

When running autodoc2 in Sphinx, you may see warnings such as:

WARNING: autodoc2_packages must not be empty [autodoc2.config_error]

All warnings emitted by sphinx-autodoc2 will have the autodoc2 type and a related subtype, so you can ignore them by adding them to the Sphinx suppress_warnings configuration in your conf.py:

suppress_warnings = [
    "autodoc2.*",  # suppress all
    "autodoc2.config_error",  # suppress specific
]

Dealing with `"reference target not found"` warnings#

When running autodoc2 in Sphinx (in nitpick mode), you may see warnings such as:

path/to/module.rst:62: WARNING: py:class reference target not found: package.module.MyClass

These are potentially from type annotations, for packages that you have not included in your intersphinx configuration.

Alternatively, they may be from imports that are named differently in the external project’s intersphinx inventory, For example, if you import MyClass from package, but the external project exposes it only as package.module.MyClass. In this case, you can use the autodoc2_replace_annotations and autodoc2_replace_bases configuration options to replace the annotation/class base with the correct reference.

autodoc2_replace_annotations = {
    "package.MyClass": "package.module.MyClass",
}
autodoc2_replace_bases = {
    "package.MyClass": "package.module.MyClass",
}

If you cannot, or do not, wish to fix them, then you can suppress these warnings using the nitpick_ignore or nitpick_ignore_regex configurations. In your conf.py:

# ignore all warnings from this package
nitpick_ignore_regex = [
    ("py:.*", r"package\..*"),
]
# ignore a specific warning
nitpick_ignore = [
    ("py:class", "package.module.MyClass"),
]

Tip

To find out what references an external project exposes to intersphinx, you can use the myst-inv command line tool. See MyST cross-project links.

Documenting only the public API (via `all`)#

By default, sphinx-autodoc2 will document all objects within each package/module, and reference direct children of them.

If you want to document only the public API of your package, you can use the __all__ variables to specify which objects to document. For example:

from .my_module import MyClass
__all__ = [
    "MyClass",
    "my_function",
]
def my_function(): ...

Using Markdown (MyST) docstrings#

By default, sphinx-autodoc2 will generate the file for each module/package as .rst, and the docstrings of each object within that module will also be interpreted as rst.

If you want to use Markdown (MyST) docstrings, you can set the autodoc2_docstring_parser_regexes for objects that use Markdown docstrings:

autodoc2_docstring_parser_regexes = [
    # this will render all docstrings as Markdown
    (r".*", "myst"),
    # this will render select docstrings as Markdown
    (r"autodoc2\..*", "myst"),
]

Alternatively, you can set the autodoc2_render_plugin configuration option in your conf.py:

autodoc2_render_plugin = "myst"

This will now create all files with the “.md” extension, and thus the docstrings will be interpreted as MyST by default.

To specify at a module level which files to render as Markdown or RestructuredText, you can set the autodoc2_render_plugin_regexes configuration option in your conf.py:

autodoc2_render_plugin_regexes = [
    (r"autodoc2\.db", "myst")
]

Which for example, created this page using Markdown docstrings: autodoc2.db

Tip

If you are looking to use Markdown docstrings, with the default sphinx-style, for example:

def my_function(a: str, b: int) -> bool:
    """This is my function.

    :param arg1: The first argument.
    :param arg2: The second argument.
    :return: The return value.
    """

Then you should enable the MyST fieldlist extension in your conf.py:

myst_enable_extensions = ["fieldlist"]

Important

It is advised that you ensure the mdit-py-plugins, which myst-parser depends on, is pinned to >0.3.4, since this version introduces improvements to the fieldlist extension (see executablebooks/mdit-py-plugins#65)

Command Line Tool#

If installed with the cli extra, sphinx-autodoc2 will install the autodoc2 command line tool.

$ pip install sphinx-autodoc2[cli]
$ autodoc2 --help

Quickstart#

Installation#

Enabling the extension#

Manually documenting select objects#

Ignoring autodoc2 warnings#

Dealing with "reference target not found" warnings#

Documenting only the public API (via __all__)#

Using Markdown (MyST) docstrings#

Command Line Tool#

Dealing with `"reference target not found"` warnings#

Documenting only the public API (via `all`)#