Scroll to navigation

SPHINX-APIDOC(1) Sphinx SPHINX-APIDOC(1)

NAME

sphinx-apidoc - 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

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

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

Force overwriting of any existing generated files.

Follow symbolic links. Defaults to False.

Do not create any files.

Suffix for the source files generated. Defaults to rst.

Maximum depth for the generated table of contents file. Defaults to 4.

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

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

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

Put documentation for each module on its own page.

Added in version 1.2.


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

Include "_private" modules.

Added in version 1.2.


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.


Put module documentation before submodule documentation.

These options are used when --full is specified:

Append module_path to sys.path.

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

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

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

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

Project templating

Added in version 2.2: Project templating options for sphinx-apidoc

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

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

SEE ALSO

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

COPYRIGHT

2007-2024, the Sphinx developers

June 29, 2024 7.3.7