sphinx-apidoc man page

sphinx-apidoc — Sphinx API doc generator tool


sphinx-apidoc [options] -o <outputdir> <sourcedir> [pathnames …]


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

sourcedir is the path to a Python package to document, and outputdir is the directory where the generated sources are placed. Any pathnames given are paths to be excluded from the generation.


sphinx-apidoc generates source files that use 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.


-o <outputdir>

Directory to place the output files. If it does not exist, it is created.

-f, --force

Force overwritting of any existing generated files.

-l, --follow-links

Follow symbolic links.

-n, --dry-run

Do not create any files.

-s <suffix>

Suffix for the source files generated. Defaults to rst.

-d <maxdepth>

Maximum depth for the generated table of contents file.

-T, --no-toc

Do not create a table of contents file. Ignored when --full is provided.

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

New 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.

New in version 1.2.


By default sphinx-apidoc processes sys.path searching for modules only. Python 3.3 introduced PEP 420 implicit namespaces that allow module path structures such as foo/bar/module.py or foo/bar/baz/__init__.py (notice that bar and foo are namespaces, not modules).

Interpret paths recursively according to PEP-0420.

-M, --module-first

Put module documentation before submodule documentation.

These options are used when --full is specified:


Append module_path to sys.path.

-H <project>

Sets the project name to put in generated files (see project).

-A <author>

Sets the author name(s) to put in generated files (see copyright).

-V <version>

Sets the project version to put in generated files (see version).

-R <release>

Sets the project release to put in generated files (see release).



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)

Referenced By

sphinx-all(1), sphinx-autogen(1), sphinx-autogen-2.7(1), sphinx-autogen-3.6(1).

The man pages sphinx-apidoc-2.7(1) and sphinx-apidoc-3.6(1) are aliases of sphinx-apidoc(1).

Mar 13, 2018 1.6.6 Sphinx