.. index::
   pair: Sphinx ; Autogen
   ! Autogen

.. _autogen_sphinx_extension:

===========================
autogen sphinx extension
===========================

.. seealso::

   - http://sphinx-doc.org/ext/autosummary.html#sphinx-autogen-generate-autodoc-stub-pages


The :program:`sphinx-autogen` script can be used to conveniently generate stub
documentation pages for items included in :rst:dir:`autosummary` listings.

For example, the command ::

    $ sphinx-autogen -o generated *.rst

will read all :rst:dir:`autosummary` tables in the :file:`*.rst` files that have the
``:toctree:`` option set, and output corresponding stub pages in directory
``generated`` for all documented items.  The generated pages by default contain
text of the form::

    sphinx.util.relative_uri
    ========================

    .. autofunction:: sphinx.util.relative_uri

If the ``-o`` option is not given, the script will place the output files in the
directories specified in the ``:toctree:`` options.


Generating stub pages automatically
===================================

If you do not want to create stub pages with :program:`sphinx-autogen`, you can
also use this new config value::

    .. confval:: autosummary_generate


Boolean indicating whether to scan all found documents for autosummary
directives, and to generate stub pages for each.

Can also be a list of documents for which stub pages should be generated.

The new files will be placed in the directories specified in the
``:toctree:`` options of the directives.