SPHINX-APIDOC(1)

NAME
sphinx-apidoc - Sphinx API doc generator tool

SYNOPSIS

sphinx-apidoc [OPTIONS] -o <OUTPUT_PATH> <MODULE_PATH> [EXCLUDE_PATTERN ...]

DESCRIPTION

sphinx-apidoc is a tool for automatic generation of Sphinx sources that, using the autodoc <#module-sphinx.ext.autodoc> extension, document a whole package in the style of other automatic API documentation tools.

MODULE_PATH is the path to a Python package to document, and OUTPUT_PATH is the directory where the generated sources are placed. Any EXCLUDE_PATTERNs given are fnmatch-style <https://docs.python.org/3/library/fnmatch.html> file and/or directory patterns that will be excluded from generation.

Warning:
        sphinx-apidoc generates source files that use sphinx.ext.autodoc <#module-sphinx.ext.autodoc> to document all found modules. If any modules have side effects on import, these will be executed by autodoc when sphinx-build is run.

        If you document scripts (as opposed to library modules), make sure their main routine is protected by a if __name__ == '__main__' condition.

OPTIONS

    -o <OUTPUT_PATH>
        Directory to place the output files. If it does not exist, it is created.

    -q  Do not output anything on standard output, only write warnings and errors to standard error.

    -f, --force
        Force overwriting of any existing generated files.

    -l, --follow-links
        Follow symbolic links. Defaults to False.

    -n, --dry-run
        Do not create or remove any files.

    -s <suffix>
        Suffix for the source files generated. Defaults to rst.

    -d <MAXDEPTH>
        Maximum depth for the generated table of contents file. Defaults to 4.

    --tocfile
        Filename for a table of contents file. Defaults to modules.

    -T, --no-toc
        Do not create a table of contents file. Ignored when --full is provided.

    --remove-old
        Remove existing files in the output directory that are not created anymore. Not compatible with --full.

    -F, --full
        Generate a full Sphinx project (conf.py, Makefile etc.) using the same mechanism as sphinx-quickstart.

    -e, --separate
        Put documentation for each module on its own page.

        Added in version 1.2.

    -E, --no-headings
        Do not create headings for the modules/packages. This is useful, for example, when docstrings already contain headings.

    -P, --private
        Include "_private" modules.

        Added in version 1.2.

    --implicit-namespaces
        Without this option, sphinx-apidoc searches sys.path </usr/share/doc/python3-doc/html/library/sys.html#sys.path> for Python packages containing __init__.py files, or single-file Python modules.

        This option instead uses PEP 420 <https://peps.python.org/pep-0420/> implicit namespaces that allow layouts paths such as foo/bar/module.py or foo/bar/baz/__init__.py (note that bar and foo are namespaces, not modules).

    -M, --module-first
        Put module documentation before submodule documentation.

These options are used when --full is specified:

    -a  Append module_path to sys.path.

    -H <project>
        Sets the project name to put in generated files (see project <#confval-project>).

    -A <author>
        Sets the author name(s) to put in generated files (see copyright <#confval-copyright>).

    -V <version>
        Sets the project version to put in generated files (see version <#confval-version>).

    -R <release>
        Sets the project release to put in generated files (see release <#confval-release>).

Project templating

Added in version 2.2: Project templating options for sphinx-apidoc

    -t, --templatedir=TEMPLATEDIR
        Template directory for template files. You can modify the templates of sphinx project files generated by apidoc. Following Jinja2 template files are allowed:

        •   module.rst.jinja

        •   package.rst.jinja

        •   toc.rst.jinja

        •   root_doc.rst.jinja

        •   conf.py.jinja

        •   Makefile.jinja

        •   Makefile.new.jinja

        •   make.bat.jinja

        •   make.bat.new.jinja

    In detail, please refer the system template files Sphinx provides. (sphinx/templates/apidoc and sphinx/templates/quickstart)

ENVIRONMENT

    SPHINX_APIDOC_OPTIONS
        A comma-separated list of option to append to generated automodule directives. Defaults to members,undoc-members,show-inheritance.

SEE ALSO

sphinx-build(1), sphinx-autogen(1)

Copyright
2007-2026, the Sphinx developers