doc: Add sphinx-autogen man page

This wasn't documented in depth anywhere, so do just that.

Signed-off-by: Stephen Finucane <stephen@that.guru>

doc/conf.py

@@ -84,6 +84,8 @@ man_pages = [
      'template generator', '', 1),
     ('man/sphinx-apidoc', 'sphinx-apidoc', 'Sphinx API doc generator tool',
      '', 1),
+    ('man/sphinx-autogen', 'sphinx-autogen', 'Generate autodoc stub pages',
+     '', 1),
 ]
 
 texinfo_documents = [

doc/ext/autosummary.rst

@@ -125,6 +125,9 @@ text of the form::
 If the ``-o`` option is not given, the script will place the output files in the
 directories specified in the ``:toctree:`` options.
 
+For more information, refer to the :doc:`sphinx-autogen documentation
+</man/sphinx-autogen>`
+
 
 Generating stub pages automatically
 -----------------------------------

doc/man/index.rst

@@ -19,3 +19,4 @@ Additional Applications
    :maxdepth: 3
 
    sphinx-apidoc
+   sphinx-autogen

doc/man/sphinx-apidoc.rst

@@ -121,7 +121,7 @@ These options are used when :option:`--full` is specified:
 See also
 --------
 
-:manpage:`sphinx-build(1)`
+:manpage:`sphinx-build(1)`, :manpage:`sphinx-autogen(1)`
 
 Author
 ------

doc/man/sphinx-autogen.rst

@@ -0,0 +1,93 @@
+sphinx-autogen
+==============
+
+Synopsis
+--------
+
+**sphinx-autogen** [*options*] <sourcefile> ...
+
+Description
+-----------
+
+:program:`sphinx-autogen` is a tool for automatic generation of Sphinx sources
+that, using the :rst:dir:`autodoc` extension, document items included in
+:rst:dir:`autosummary` listing(s).
+
+*sourcefile* is the path to one or more reStructuredText documents containing
+:rst:dir:`autosummary` entries with the ``:toctree::`` option set. *sourcefile*
+can be an :py:module:`fnmatch`-style pattern.
+
+Options
+-------
+
+.. program:: sphinx-autogen
+
+.. option:: -o <outputdir>
+
+   Directory to place the output file. If it does not exist, it is created.
+   Defaults to the value passed to the ``:toctree:`` option.
+
+.. option:: -s <suffix>, --suffix <suffix>
+
+   Default suffix to use for generated files. Defaults to ``rst``.
+
+.. option:: -t <templates>, --templates <templates>
+
+   Custom template directory. Defaults to ``None``.
+
+.. option:: -i, --imported-members
+
+   Document imported members.
+
+Example
+-------
+
+Given the following directory structure::
+
+    docs
+    ├── index.rst
+    └── ...
+    foobar
+    ├── foo
+    │   └── __init__.py
+    └── bar
+        ├── __init__.py
+        └── baz
+            └── __init__.py
+
+and assuming ``docs/index.rst`` contained the following:
+
+.. code-block:: rst
+
+    Modules
+    =======
+
+    .. autosummary::
+       :toctree: modules
+
+       foobar.foo
+       foobar.bar
+       foobar.bar.baz
+
+If you run the following:
+
+.. code-block:: bash
+
+    $ sphinx-autodoc doc/index.rst
+
+then the following stub files will be created in ``docs``::
+
+    docs
+    ├── index.rst
+    └── modules
+        ├── foobar.bar.rst
+        ├── foobar.bar.baz.rst
+        └── foobar.foo.rst
+
+and each of those files will contain a :rst:dir:`autodoc` directive and some
+other information.
+
+See also
+--------
+
+:manpage:`sphinx-build(1)`, :manpage:`sphinx-apidoc(1)`