Hide navigation sidebar
Hide table of contents sidebar
Skip to content
Back to top
View this page
Toggle table of contents sidebar

# 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

See also

Package analysis for more information on how to configure the packages to document.

Tip

If you don’t want to include the `apidocs` directory in your repository, you may want to add a `.gitignore` in the `apidocs` folder with `*` in it.

## Manually documenting select objects

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

1. auto mode (default) - Automatically generate files for all modules and packages specified by the `autodoc2_packages` configuration option.

2. 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(): ...

See also

The Python import documentation

To enable this feature, set the `autodoc2_module_all_regexes` configuration option in your `conf.py`:

    autodoc2_module_all_regexes = [
        r"my_package\..*",
    ]

You can see an axample of this in the Example documentation of the `aiida` package.

Note, when following `__all__` imports, since the `:canonical:` option is added to each object, intersphinx will record both the canonical and non-canonical names of the object. For example, if there is a package `my_package` with the following `__init__.py`:

    from .my_module import MyClass
    __all__ = [
        "MyClass",
    ]

Then you will be able to reference `MyClass` in your documentation as either `my_package.MyClass` or `my_package.my_module.MyClass`.

## 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