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_PATTERN*s 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.

   New 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.

   New 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 ]-

New 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
========

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