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.
Advertencia
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.
-
-f
,
--force
¶
Force overwriting 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.
-
--tocfile
¶
Filename for a table of contents file. Defaults to
modules
.
-
-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.
Nuevo en la versión 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.
Nuevo en la versión 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.
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)