From c244a7c9a94fc3451024f5488ffd631827072e81 Mon Sep 17 00:00:00 2001 From: Stephen Finucane Date: Wed, 3 May 2017 16:33:26 +0100 Subject: [PATCH] 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 --- doc/invocation.rst | 123 +------------------------------------- doc/man/sphinx-apidoc.rst | 123 ++++++++++++++++++++++++++++---------- 2 files changed, 93 insertions(+), 153 deletions(-) diff --git a/doc/invocation.rst b/doc/invocation.rst index d0dedbd8b..80616d0c9 100644 --- a/doc/invocation.rst +++ b/doc/invocation.rst @@ -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 - `_. - 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 `. diff --git a/doc/man/sphinx-apidoc.rst b/doc/man/sphinx-apidoc.rst index be0c3d3a3..4586d43f5 100644 --- a/doc/man/sphinx-apidoc.rst +++ b/doc/man/sphinx-apidoc.rst @@ -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 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 for the source files generated, default is ``rst``. --d 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 --a Append module_path to sys.path. --H Project name to put into the configuration. --A Author name(s) to put into the configuration. --V Project version. --R 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 for the source files generated. Defaults to ``rst``. + +.. option:: -d + + 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 + + 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`). See also -------- :manpage:`sphinx-build(1)` - Author ------