Add a rudimentary manpage for sphinx-apidoc.

3 files changed, 57 insertions, 1 deletions

diff --git a/doc/conf.py b/doc/conf.py
index a1d0e8ce5..1b8ba3e4d 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -62,6 +62,8 @@ man_pages = [
      '', 1),
     ('man/sphinx-quickstart', 'sphinx-quickstart', 'Sphinx documentation '
      'template generator', '', 1),
+    ('man/sphinx-apidoc', 'sphinx-apidoc', 'Sphinx API doc generator tool',
+     '', 1),
 ]
 
 texinfo_documents = [
diff --git a/doc/man/sphinx-apidoc.rst b/doc/man/sphinx-apidoc.rst
new file mode 100644
index 000000000..4b65cc632
--- /dev/null
+++ b/doc/man/sphinx-apidoc.rst
@@ -0,0 +1,52 @@
+:orphan:
+
+sphinx-apidoc manual page
+=========================
+
+Synopsis
+--------
+
+**sphinx-apidoc** [*options*] -o <*outputdir*> <*sourcedir*> [*filenames* ...]
+
+
+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.
+
+
+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.
+-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.
+
+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`.
+
+
+See also
+--------
+
+:manpage:`sphinx-build(1)`
+
+
+Author
+------
+
+Etienne Desautels, <etienne.desautels@gmail.com>, Georg Brandl
+<georg@python.org> et al.
diff --git a/sphinx/apidoc.py b/sphinx/apidoc.py
index 96159ba7f..34381be0c 100644
--- a/sphinx/apidoc.py
+++ b/sphinx/apidoc.py
@@ -303,7 +303,9 @@ Note: By default this script will not overwrite already created files.""")
             mastertocmaxdepth = opts.maxdepth,
             mastertoctree = text,
         )
-        qs.generate(d, silent=True)
+        # XXX overwrites even without --force
+        if not opts.dryrun:
+            qs.generate(d, silent=True)
         print 'Creating quickstart project and Makefile.'
     elif not opts.notoc:
         create_modules_toc_file(modules, opts)