mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
d7e1bfeb4b
A common "gotcha" of re-running `sphinx-apidoc`, is that if the modules API changes it will not remove old files, leading to build errors for files not in a `toctree` This commit introduces a `--remove-old` option to remove these files. Note, a key detail here is that we don't want to simply clear the directory before running `sphinx-apidoc`, since this would lead to all files having a new `mtime`, and then `sphinx-build` would rebuild all of them even if they have not changed. So we must first collect the list of all correct files, then remove any not in the list. The commit also improves some typing of the code and replace `os.path` by `pathlib.Path` in most instances
178 lines
4.6 KiB
ReStructuredText
178 lines
4.6 KiB
ReStructuredText
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 :py:mod:`~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_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. Defaults to ``False``.
|
|
|
|
.. option:: -n, --dry-run
|
|
|
|
Do not create or remove any files.
|
|
|
|
.. option:: -s <suffix>
|
|
|
|
Suffix for the source files generated. Defaults to ``rst``.
|
|
|
|
.. option:: -d <MAXDEPTH>
|
|
|
|
Maximum depth for the generated table of contents file. Defaults to ``4``.
|
|
|
|
.. 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:: --remove-old
|
|
|
|
Remove existing files in the output directory
|
|
that are not created anymore.
|
|
Not compatible with :option:`--full`.
|
|
|
|
.. 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 <project>
|
|
|
|
Sets the project name to put in generated files (see :confval:`project`).
|
|
|
|
.. option:: -A <author>
|
|
|
|
Sets the author name(s) to put in generated files (see
|
|
:confval:`copyright`).
|
|
|
|
.. option:: -V <version>
|
|
|
|
Sets the project version to put in generated files (see :confval:`version`).
|
|
|
|
.. option:: -R <release>
|
|
|
|
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``
|
|
* ``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
|
|
-----------
|
|
|
|
.. 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
|