sphinx-apidoc¶
Synopsis¶
sphinx-apidoc [options] -o <outputdir> <sourcedir> [pathnames …]
Description¶
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.
Warning
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.
Options¶
-
-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.
-
-F,--full¶ Generate a full Sphinx project (
conf.py,Makefileetc.) 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.
-
--implicit-namespaces¶ 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.pyorfoo/bar/baz/__init__.py(notice thatbarandfooare 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:
-
-a¶ Append module_path to sys.path.
Environment¶
-
SPHINX_APIDOC_OPTIONS¶ A comma-separated list of option to append to generated
automoduledirectives. Defaults tomembers,undoc-members,show-inheritance.
See also¶
sphinx-build(1), sphinx-autogen(1)