Georg Brandl avatar Georg Brandl committed 51f7bca

Closes #585: document sphinx-apidoc.

Comments (0)

Files changed (3)

doc/invocation.rst

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

 Synopsis
 --------
 
-**sphinx-apidoc** [*options*] -o <*outputdir*> <*sourcedir*> [*filenames* ...]
+**sphinx-apidoc** [*options*] -o <*outputdir*> <*sourcedir*> [*pathnames* ...]
 
 
 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
 -------
 
 -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
 
 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
 ---------------------------
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.