GNU nano 5.3 sphinx-apidoc.rst sphinx-apidoc

Synopsis

sphinx-apidoc [OPTIONS] -o <OUTPUT_PATH> <MODULE_PATH> [EXCLUDE_PATTERN ...]

Description

:program:sphinx-apidoc is a tool for automatic generation of Sphinx sources that, using the :rst:dir: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_PATTERN\s given are fnmatch-style_ file and/or directory patterns that will be excluded from generation.

.. _fnmatch-style: https://docs.python.org/3/library/fnmatch.html

.. warning::

sphinx-apidoc generates source files that use :mod: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

.. program:: sphinx-apidoc

.. option:: -o <OUTPUT_PATH>

Directory to place the output files. If it does not exist, it is created.

.. option:: -q

Do not output anything on standard output, only write warnings and errors to standard error.

.. option:: -f, --force

Force overwriting of any existing generated files.

.. option:: -l, --follow-links

Follow symbolic links.

.. option:: -n, --dry-run

Do not create any files.

.. option:: -s

Suffix for the source files generated. Defaults to rst.

.. option:: -d

Maximum depth for the generated table of contents file.

.. option:: --tocfile

Filename for a table of contents file. Defaults to modules.

.. option:: -T, --no-toc

Do not create a table of contents file. Ignored when :option:--full is provided.

.. option:: -F, --full

Generate a full Sphinx project (conf.py, Makefile etc.) using the same mechanism as :program:sphinx-quickstart.

.. option:: -e, --separate

Put documentation for each module on its own page.

.. versionadded:: 1.2

.. option:: -E, --no-headings

Do not create headings for the modules/packages. This is useful, for example, when docstrings already contain headings.

.. option:: -P, --private

Include "_private" modules.

.. versionadded:: 1.2

.. option:: --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.

.. option:: -M, --module-first

Put module documentation before submodule documentation.

These options are used when :option:--full is specified:

.. option:: -a

Append module_path to sys.path.

.. option:: -H

Sets the project name to put in generated files (see :confval:project).

.. option:: -A

Sets the author name(s) to put in generated files (see :confval:copyright).

.. option:: -V

Sets the project version to put in generated files (see :confval:version).

.. option:: -R

Sets the project release to put in generated files (see :confval:release).

.. rubric:: Project templating

.. versionadded:: 2.2 Project templating options for sphinx-apidoc

.. option:: -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
• master_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

.. envvar:: SPHINX_APIDOC_OPTIONS

A comma-separated list of option to append to generated automodule directives. Defaults to members,undoc-members,show-inheritance.

See also

:manpage:sphinx-build(1), :manpage:sphinx-autogen(1)

.. _fnmatch: https://docs.python.org/3/library/fnmatch.html