sphinx-apidoc¶
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
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 file and/or directory patterns that will be excluded from 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 <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
.
- --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¶
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
orfoo/bar/baz/__init__.py
(notice thatbar
andfoo
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:
- -a¶
Append module_path to sys.path.
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
andsphinx/templates/quickstart
)
Environment¶
- SPHINX_APIDOC_OPTIONS¶
A comma-separated list of option to append to generated
automodule
directives. Defaults tomembers,undoc-members,show-inheritance
.
See also¶
sphinx-build(1), sphinx-autogen(1)