add sphinx extensions

1 files changed, 121 insertions, 40 deletions

diff --git a/docs/style-guide.rst b/docs/style-guide.rst
index 02f8c18fa..0adea0e38 100644
--- a/docs/style-guide.rst
+++ b/docs/style-guide.rst
@@ -1062,11 +1062,74 @@ The above code renders as follows.
 
 This **word** is in bold text.
 
+.. seealso::
+
+    See also the Sphinx documentation for the :ref:`rst-primer`.
+
+
+.. _style-guide-cross-references:
+
+Cross-references
+^^^^^^^^^^^^^^^^
+
+To create cross-references to a document, arbitrary location, object, or other items, use variations of the following syntax.
+
+* ``:role:`target``` creates a link to the item named ``target`` of the type indicated by ``role``, with the link's text as the title of the target. ``target`` may need to be disambiguated between documentation sets linked through intersphinx, in which case the syntax would be ``deform:overview``.
+* ``:role:`~target``` displays the link as only the last component of the target.
+* ``:role:`title <target>``` creates a custom title, instead of the default title of the target.
+
+
+.. _style-guide-cross-referencing-documents:
+
+Cross-referencing documents
+```````````````````````````
+
+To link to pages within this documentation:
+
+.. code-block:: rst
+
+    :doc:`quick_tour`
+
+The above code renders as follows.
 
-.. _style-guide-python:
+:doc:`quick_tour`
+
+
+.. _style-guide-cross-referencing-arbitrary-locations:
+
+Cross-referencing arbitrary locations
+`````````````````````````````````````
+
+To support cross-referencing to arbitrary locations in any document and between documentation sets via intersphinx, the standard reST labels are used. For this to work, label names must be unique throughout the entire documentation including externally linked intersphinx references. There are two ways in which you can refer to labels, if they are placed directly before a section title, a figure, or table with a caption, or at any other location. The following section has a label with the syntax ``.. _label_name:`` followed by the section title.
+
+.. code-block:: rst
+
+    .. _i18n_chapter:
+
+    Internationalization and Localization
+    =====================================
+
+To generate a link to that section with its title, use the following syntax.
+
+.. code-block:: rst
+
+    :ref:`i18n_chapter`
+
+The above code renders as follows.
+
+:ref:`i18n_chapter`
+
+The same syntax works figures and tables with captions.
+
+For labels that are not placed as mentioned, the link must be given an explicit title, such as ``:ref:`Link title <label-name>```.
+
+.. seealso:: See also the Sphinx documentation, :ref:`inline-markup`.
+
+
+.. _style-guide-cross-referencing-python:
 
 Python modules, classes, methods, and functions
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+```````````````````````````````````````````````
 
 Python module names use the ``mod`` directive, with the module name as the argument.
 
@@ -1108,81 +1171,99 @@ The above code renders as follows.
 
 :func:`pyramid.renderers.render_to_response`
 
-.. seealso::
-
-    See also the Sphinx documentation for the :ref:`rst-primer`.
+Note that you can use either or combine the ``~`` and ``.`` prefixes. However, we prefer not to use the ``.`` prefix because Sphinx might generate an error if it cannot disambiguate the reference.
 
+.. code-block:: rst
 
-.. _style-guide-cross-references:
+    :func:`~.render_to_response`
 
-Cross-references
-^^^^^^^^^^^^^^^^
+The above code renders as follows.
 
-To create cross-references to an arbitrary location, object, document, or other items, use variations of the following syntax.
+:func:`~.render_to_response`
 
-* ``:role:`target``` creates a link to the item named ``target`` of the type indicated by ``role``, with the link's text as the title of the target. ``target`` may need to be disambiguated between documentation sets linked through intersphinx, in which case the syntax would be ``deform:overview``.
-* ``:role:`~target``` displays the link as only the last component of the target.
-* ``:role:`title <target>``` creates a custom title, instead of the default title of the target.
 
+.. _style-guide-role-app-pyramid:
 
-.. _style-guide-cross-referencing-documents:
+The role ``:app:`Pyramid```
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Cross-referencing documents
-```````````````````````````
+We use the special role ``app`` to refer to the application "Pyramid".
 
-To link to pages within this documentation:
 
 .. code-block:: rst
 
-    :doc:`quick_tour`
+    :app:`Pyramid`
 
 The above code renders as follows.
 
-:doc:`quick_tour`
+:app:`Pyramid`
 
 
-.. _style-guide-cross-referencing-arbitrary-locations:
+.. _style-guide-sphinx-extensions:
 
-Cross-referencing arbitrary locations
-`````````````````````````````````````
+Sphinx extensions
+-----------------
 
-To support cross-referencing to arbitrary locations in any document and between documentation sets via intersphinx, the standard reST labels are used. For this to work, label names must be unique throughout the entire documentation including externally linked intersphinx references. There are two ways in which you can refer to labels, if they are placed directly before a section title, a figure, or table with a caption, or at any other location. The following section has a label with the syntax ``.. _label_name:`` followed by the section title.
+We use several Sphinx extensions to add features to our documentation. Extensions need to be enabled and configured in ``docs/conf.py`` before they can be used.
 
-.. code-block:: rst
 
-    .. _i18n_chapter:
+.. _style-guide-sphinx-extension-autodoc:
 
-    Internationalization and Localization
-    =====================================
+:mod:`sphinx.ext.autodoc`
+-------------------------
 
-To generate a link to that section with its title, use the following syntax.
+API documentation uses the Sphinx extension :mod:`sphinx.ext.autodoc` to include documentation from docstrings.
 
-.. code-block:: rst
+See the source of any documentation within the ``docs/api/`` directory for conventions and usage, as well as the Sphinx extension's :mod:`documentation <sphinx.ext.autodoc>`.
 
-    :ref:`i18n_chapter`
 
-The above code renders as follows.
+.. _style-guide-sphinx-extension-doctest:
 
-:ref:`i18n_chapter`
+:mod:`sphinx.ext.doctest`
+-------------------------
 
-The same syntax works figures and tables with captions.
+:mod:`sphinx.ext.doctest` allows you to test code snippets in the documentation in a natural way. It works by collecting specially-marked up code blocks and running them as doctest tests. We have only a few tests in our Pyramid documentation which can be found in ``narr/sessions.rst`` and ``narr/hooks.rst``.
 
-For labels that are not placed as mentioned, the link must be given an explicit title, such as ``:ref:`Link title <label-name>```.
 
-.. seealso:: See also the Sphinx documentation, :ref:`inline-markup`.
+.. _style-guide-sphinx-extension-intersphinx:
 
+:mod:`sphinx.ext.intersphinx`
+-----------------------------
 
+:mod:`sphinx.ext.intersphinx` generates links to the documentation of objects in other projects.
 
 
-:app:`Pyramid`
+.. _style-guide-sphinx-extension-todo:
 
+:mod:`sphinx.ext.todo`
+----------------------
+
+:mod:`sphinx.ext.todo` adds support for todo items.
+
+
+.. _style-guide-sphinx-extension-viewcode:
+
+:mod:`sphinx.ext.viewcode`
+--------------------------
+
+:mod:`sphinx.ext.viewcode` looks at your Python object descriptions and tries to find the source files where the objects are contained. When found, a separate HTML page will be output for each module with a highlighted version of the source code, and a link will be added to all object descriptions that leads to the source code of the described object. A link back from the source to the description will also be inserted.
 
-API documentation
------------------
 
-.. automodule:: pyramid.i18n
+.. _style-guide-sphinx-extension-repoze-sphinx-autointerface:
 
-.. .. autoclass:: TranslationString
+`repoze.sphinx.autointerface <https://pypi.python.org/pypi/repoze.sphinx.autointerface>`_
+-----------------------------------------------------------------------------------------
 
-.. .. autofunction:: TranslationStringFactory
+`repoze.sphinx.autointerface <https://pypi.python.org/pypi/repoze.sphinx.autointerface>`_ auto-generates API docs from Zope interfaces.
+
+
+.. _style-guide-script-documentation:
+
+Script documentation
+--------------------
+
+We currently use `sphinxcontrib-programoutput <https://pypi.python.org/pypi/sphinxcontrib-programoutput>`_ to generate program output of the p* scripts. It is no longer maintained and may cause future builds of the documentation to fail.
+
+.. todo::
 
+    See `issue #2804 <https://github.com/Pylons/pyramid/issues/2804>`_ for further discussion.