sphinx-apidoc - Man Page
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 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 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.
- -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 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:
- -a
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).
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_t
- package.rst_t
- toc.rst_t
- root_doc.rst_t
- conf.py_t
- Makefile_t
- Makefile.new_t
- make.bat_t
- make.bat.new_t
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
Copyright
2007-2024, the Sphinx developers
Referenced By
sphinx-all(1), sphinx-autogen(1).