SPHINX_APIDOC_OPTIONS
A comma-separated list of option to append to generated automodule directives. Defaults to members,undoc-members,show-inheritance.
sphinx-apidoc1
Sphinx api doc generator tool
Usage
sphinx-apidoc [OPTIONS]
-o
<OUTPUT_PATH>
<MODULE_PATH>
[EXCLUDE_PATTERN ...]
Overview
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
--fullis 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,Makefileetc.) using the same mechanism assphinx-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-apidocsearchessys.path<https://docs.python.org/3/library/sys.html#sys.path> for Python packages containing__init__.pyfiles, 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.pyorfoo/bar/baz/__init__.py(note thatbarandfooare 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/apidocandsphinx/templates/quickstart)
Environment
Releases
8 releases since Debian 7 (Wheezy); the text changed 7 times.
--follow-links since Debian 8 (Jessie);
--implicit-namespaces since Debian 10 (Buster);
--module-first since Debian 10 (Buster);
--no-headings since Debian 8 (Jessie);
--private since Debian 8 (Jessie);
--remove-old since Debian 13 (Trixie);
--separate since Debian 8 (Jessie);
--templatedir since Debian 11 (Bullseye);
--tocfile since Debian 10 (Buster);
-A since Debian 10 (Buster);
-E since Debian 8 (Jessie);
-H since Debian 10 (Buster);
-M since Debian 10 (Buster);
-P since Debian 8 (Jessie);
-R since Debian 10 (Buster);
-V since Debian 10 (Buster);
-a since Debian 10 (Buster);
-d since Debian 10 (Buster);
-e since Debian 8 (Jessie);
-l since Debian 8 (Jessie);
-o since Debian 10 (Buster);
-q since Debian 11 (Bullseye);
-s since Debian 10 (Buster);
-t since Debian 11 (Bullseye).