Closes #585: document sphinx-apidoc.

doc/invocation.rst

@@ -14,6 +14,8 @@ you don't need to specify any *filenames*.
 
 The :program:`sphinx-build` script has several options:
 
+.. program:: sphinx-build
+
 .. option:: -b buildername
 
    The most important option: it selects a builder.  The most common builders
@@ -183,3 +185,72 @@ variables to customize behavior:
 .. describe:: SPHINXOPTS
 
    Additional options for :program:`sphinx-build`.
+
+
+.. _invocation-apidoc:
+
+Invocation of sphinx-apidoc
+===========================
+
+The :program:`sphinx-apidoc` generates completely automatic API documentation
+for a Python package.  It is called like this::
+
+     $ 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.
+
+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:: -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:: -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:: -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:: -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`).

doc/man/sphinx-apidoc.rst

@@ -6,7 +6,7 @@ sphinx-apidoc manual page
 Synopsis
 --------
 
-**sphinx-apidoc** [*options*] -o <*outputdir*> <*sourcedir*> [*filenames* ...]
+**sphinx-apidoc** [*options*] -o <*outputdir*> <*sourcedir*> [*pathnames* ...]
 
 
 Description
@@ -16,6 +16,9 @@ Description
 that, using the 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.
+
 
 Options
 -------
@@ -35,8 +38,8 @@ These options are used with ``-F``:
 
 -H <project>    Project name to put into the configuration.
 -A <author>     Author name(s) to put into the configuration.
--V <version>    Project version, see :confval:`release`.
--R <release>    Project release, see :confval:`release`.
+-V <version>    Project version.
+-R <release>    Project release.
 
 
 See also

doc/tutorial.rst

@@ -26,6 +26,9 @@ configuration values from a few questions it asks you.  Just run ::
 
 and answer its questions.  (Be sure to say yes to the "autodoc" extension.)
 
+There is also an automatic "API documentation" generator called
+:program:`sphinx-apidoc`; see :ref:`invocation-apidoc` for details.
+
 
 Defining document structure
 ---------------------------