mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
doc: Update sphinx-apidoc man page
This man page wasn't making full use of Sphinx's own features. Update it to do so, and remove the duplicated information from 'invocation'. Signed-off-by: Stephen Finucane <stephen@that.guru>
This commit is contained in:
Stephen Finucane
@@ -442,125 +442,4 @@ variable to your environment. For example:
|
||||
Invocation of sphinx-apidoc
|
||||
===========================
|
||||
|
||||
The :program:`sphinx-apidoc` generates completely automatic API documentation
|
||||
for a Python package. It is called like this:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ sphinx-apidoc [options] -o outputdir packagedir [pathnames]
|
||||
|
||||
where *packagedir* is the path to the package to document, and *outputdir* is
|
||||
the directory where the generated sources are placed. Any *pathnames* given
|
||||
are paths to be excluded ignored during generation.
|
||||
|
||||
.. warning::
|
||||
|
||||
``sphinx-apidoc`` generates reST 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.
|
||||
|
||||
|
||||
The :program:`sphinx-apidoc` script has several options:
|
||||
|
||||
.. program:: sphinx-apidoc
|
||||
|
||||
.. option:: -o outputdir
|
||||
|
||||
Gives the directory in which to place the generated output.
|
||||
|
||||
.. option:: -f, --force
|
||||
|
||||
Normally, sphinx-apidoc does not overwrite any files. Use this option to
|
||||
force the overwrite of all files that it generates.
|
||||
|
||||
.. option:: -n, --dry-run
|
||||
|
||||
With this option given, no files will be written at all.
|
||||
|
||||
.. option:: -e, --separate
|
||||
|
||||
Put documentation for each module on its own page.
|
||||
|
||||
.. versionadded:: 1.2
|
||||
|
||||
.. option:: -P, --private
|
||||
|
||||
Include "_private" modules.
|
||||
|
||||
.. versionadded:: 1.2
|
||||
|
||||
.. option:: -s suffix
|
||||
|
||||
This option selects the file name suffix of output files. By default, this
|
||||
is ``rst``.
|
||||
|
||||
.. option:: -d maxdepth
|
||||
|
||||
This sets the maximum depth of the table of contents, if one is generated.
|
||||
|
||||
.. option:: -l, --follow-links
|
||||
|
||||
This option makes sphinx-apidoc follow symbolic links when recursing the
|
||||
filesystem to discover packages and modules. You may need it if you want
|
||||
to generate documentation from a source directory managed by
|
||||
`collective.recipe.omelette
|
||||
<https://pypi.python.org/pypi/collective.recipe.omelette/>`_.
|
||||
By default, symbolic links are skipped.
|
||||
|
||||
.. versionadded:: 1.2
|
||||
|
||||
.. option:: -T, --no-toc
|
||||
|
||||
This prevents the generation of a table-of-contents file ``modules.rst``.
|
||||
This has no effect when :option:`--full` is given.
|
||||
|
||||
.. option:: -E, --no-headings
|
||||
|
||||
Don't create headings for the module/package packages (e.g. when the
|
||||
docstrings already contain them).
|
||||
|
||||
.. versionadded:: 1.2
|
||||
|
||||
.. option:: -F, --full
|
||||
|
||||
This option makes sphinx-apidoc create a full Sphinx project, using the same
|
||||
mechanism as :program:`sphinx-quickstart`. Most configuration values are set
|
||||
to default values, but you can influence the most important ones using the
|
||||
following options.
|
||||
|
||||
.. 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).
|
||||
|
||||
Specifying this option interprets paths recursively according to PEP-0420.
|
||||
|
||||
.. option:: -M
|
||||
|
||||
This option makes sphinx-apidoc put module documentation before submodule
|
||||
documentation.
|
||||
|
||||
.. 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`).
|
||||
Refer to the :doc:`sphinx-apidoc man page <man/sphinx-apidoc>`.
|
||||
|
||||
@@ -1,23 +1,21 @@
|
||||
:orphan:
|
||||
|
||||
sphinx-apidoc manual page
|
||||
=========================
|
||||
sphinx-apidoc
|
||||
=============
|
||||
|
||||
Synopsis
|
||||
--------
|
||||
|
||||
**sphinx-apidoc** [*options*] -o <*outputdir*> <*sourcedir*> [*pathnames* ...]
|
||||
|
||||
|
||||
Description
|
||||
-----------
|
||||
|
||||
:program:`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.
|
||||
that, using the :rst:dir:`autodoc` extension, document a whole package in the
|
||||
style of other automatic API documentation tools.
|
||||
|
||||
*sourcedir* must point to a Python package. Any *pathnames* given are paths to
|
||||
be excluded from the generation.
|
||||
*sourcedir* is the path to a Python package to document, and *outputdir* is the
|
||||
directory where the generated sources are placed. Any *pathnames* given are
|
||||
paths to be excluded from the generation.
|
||||
|
||||
.. warning::
|
||||
|
||||
@@ -28,40 +26,103 @@ be excluded from the generation.
|
||||
If you document scripts (as opposed to library modules), make sure their main
|
||||
routine is protected by a ``if __name__ == '__main__'`` condition.
|
||||
|
||||
|
||||
Options
|
||||
-------
|
||||
|
||||
-o <outputdir> Directory to place the output files. If it does not exist,
|
||||
it is created.
|
||||
-f, --force Usually, apidoc does not overwrite files, unless this option
|
||||
is given.
|
||||
-l, --follow-links Follow symbolic links.
|
||||
-n, --dry-run If given, apidoc does not create any files.
|
||||
-s <suffix> Suffix for the source files generated, default is ``rst``.
|
||||
-d <maxdepth> Maximum depth for the generated table of contents file.
|
||||
-T, --no-toc Do not create a table of contents file.
|
||||
-F, --full If given, a full Sphinx project is generated (``conf.py``,
|
||||
``Makefile`` etc.) using sphinx-quickstart.
|
||||
-e, --separate Put each module file in its own page.
|
||||
-E, --no-headings Don't create headings for the modules/packages
|
||||
-P, --private Include "_private" modules
|
||||
.. program:: sphinx-apidoc
|
||||
|
||||
These options are used with ``-F``:
|
||||
.. option:: -o <outputdir>
|
||||
|
||||
-a Append module_path to sys.path.
|
||||
-H <project> Project name to put into the configuration.
|
||||
-A <author> Author name(s) to put into the configuration.
|
||||
-V <version> Project version.
|
||||
-R <release> Project release.
|
||||
Directory to place the output files. If it does not exist, it is created.
|
||||
|
||||
.. option:: -f, --force
|
||||
|
||||
Force overwritting of any existing generated files.
|
||||
|
||||
.. option:: -l, --follow-links
|
||||
|
||||
Follow symbolic links.
|
||||
|
||||
.. option:: -n, --dry-run
|
||||
|
||||
Do not create 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.
|
||||
|
||||
.. 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
|
||||
|
||||
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`).
|
||||
|
||||
See also
|
||||
--------
|
||||
|
||||
:manpage:`sphinx-build(1)`
|
||||
|
||||
|
||||
Author
|
||||
------
|
||||
|
||||
|
||||
Reference in New Issue
Block a user