Merge pull request #2837 from stevepiercy/style-guide

Add more sections to the Style Guide

1 files changed, 412 insertions, 94 deletions

diff --git a/docs/style-guide.rst b/docs/style-guide.rst
index 73cba0859..0adea0e38 100644
--- a/docs/style-guide.rst
+++ b/docs/style-guide.rst
@@ -3,9 +3,9 @@
 Style Guide
 ===========
 
-.. admonition:: description
-
-   This chapter describes how to edit, update, and build the :app:`Pyramid` documentation. For coding style guidelines, see `Coding Style <http://docs.pylonsproject.org/en/latest/community/codestyle.html#coding-style>`_.
+.. meta::
+   :description: This chapter describes how to edit, update, and build the Pyramid documentation.
+   :keywords: Pyramid, Style Guide
 
 
 .. _style-guide-introduction:
@@ -15,6 +15,8 @@ Introduction
 
 This chapter provides details of how to contribute updates to the documentation following style guidelines and conventions. We provide examples, including reStructuredText code and its rendered output for both visual and technical reference.
 
+For coding style guidelines, see `Coding Style <http://docs.pylonsproject.org/en/latest/community/codestyle.html#coding-style>`_.
+
 
 .. _style-guide-contribute:
 
@@ -33,18 +35,126 @@ When submitting a pull request for the first time in a project, sign `CONTRIBUTO
 Location, referencing, and naming of files
 ------------------------------------------
 
-- reStructuredText (reST) files must be located in ``docs/`` and its subdirectories.
-- Image files must be located in ``docs/_static/``.
-- reST directives must refer to files either relative to the source file or absolute from the top source directory. For example, in ``docs/narr/source.rst``, you could refer to a file in a different directory as either ``.. include:: ../diff-dir/diff-source.rst`` or ``.. include:: /diff-dir/diff-source.rst``.
-- File names should be lower-cased and have words separated with either a hyphen "-" or an underscore "_".
-- reST files must have an extension of ``.rst``.
-- Image files may be any format but must have lower-cased file names and have standard file extensions that consist three letters (``.gif``, ``.jpg``, ``.png``, ``.svg``).  ``.gif`` and ``.svg`` are not currently supported by PDF builders in Sphinx, but you can allow the Sphinx builder to automatically select the correct image format for the desired output by replacing the three-letter file extension with ``*``.  For example:
+* reStructuredText (reST) files must be located in ``docs/`` and its subdirectories.
+* Image files must be located in ``docs/_static/``.
+* reST directives must refer to files either relative to the source file or absolute from the top source directory. For example, in ``docs/narr/source.rst``, you could refer to a file in a different directory as either ``.. include:: ../diff-dir/diff-source.rst`` or ``.. include:: /diff-dir/diff-source.rst``.
+* File names should be lower-cased and have words separated with either a hyphen "-" or an underscore "_".
+* reST files must have an extension of ``.rst``.
+* Image files may be any format but must have lower-cased file names and have standard file extensions that consist three letters (``.gif``, ``.jpg``, ``.png``, ``.svg``).  ``.gif`` and ``.svg`` are not currently supported by PDF builders in Sphinx, but you can allow the Sphinx builder to automatically select the correct image format for the desired output by replacing the three-letter file extension with ``*``.  For example:
 
   .. code-block:: rst
 
-     .. image:: ../_static/pyramid_request_processing.-
+      .. image:: ../_static/pyramid_request_processing.
+
+  will select the image ``pyramid_request_processing.svg`` for the HTML documentation builder, and ``pyramid_request_processing.png`` for the PDF builder. See the related `Stack Overflow post <http://stackoverflow.com/questions/6473660/using-sphinx-docs-how-can-i-specify-png-image-formats-for-html-builds-and-pdf-im/6486713#6486713>`_.
+
 
-  will select the image ``pyramid_request_processing.svg`` for the HTML documentation builder, and ``pyramid_request_processing.png`` for the PDF builder. See the related [Stack Overflow post](http://stackoverflow.com/questions/6473660/using-sphinx-docs-how-can-i-specify-png-image-formats-for-html-builds-and-pdf-im/6486713#6486713).
+.. _style-guide-table-of-contents-tree:
+
+Table of contents tree
+----------------------
+
+To insert a table of contents (TOC), use the ``toctree`` directive. Entries listed under the ``toctree`` directive follow :ref:`location conventions <style-guide-file-conventions>`. A numeric ``maxdepth`` option may be given to indicate the depth of the tree; by default, all levels are included.
+
+.. code-block:: rst
+
+    .. toctree::
+        :maxdepth: 2
+
+        narr/introduction
+        narr/install
+
+The above code renders as follows.
+
+.. toctree::
+    :maxdepth: 2
+
+    narr/introduction
+    narr/install
+
+Globbing can be used.
+
+.. code-block:: rst
+
+    .. toctree::
+        :maxdepth: 1
+        :glob:
+
+        pscripts/index
+        pscripts/*
+
+The above code renders as follows.
+
+.. toctree::
+    :maxdepth: 1
+    :glob:
+
+    pscripts/index
+    pscripts/*
+
+To notify Sphinx of the document hierarchy, but not insert links into the document at the location of the directive, use the option ``hidden``. This makes sense when you want to insert these links yourself, in a different style, or in the HTML sidebar.
+
+.. code-block:: rst
+
+    .. toctree::
+        :hidden:
+
+        quick_tour
+
+    * :doc:`quick_tour` gives an overview of the major features in Pyramid, covering a little about a lot.
+
+The above code renders as follows.
+
+.. toctree::
+    :hidden:
+
+    quick_tour
+
+* :doc:`quick_tour` gives an overview of the major features in Pyramid, covering a little about a lot.
+
+.. seealso:: Sphinx documentation of :ref:`toctree-directive`.
+
+
+.. _style-guide-glossary:
+
+Glossary
+--------
+
+A glossary defines terms used throughout the documentation.
+
+The glossary file must be named ``glossary.rst``. Its content must begin with the directive ``glossary``. An optional ``sorted`` argument should be used to sort the terms alphabetically when rendered, making it easier for the user to find a given term. Without the argument ``sorted``, terms will appear in the order of the ``glossary`` source file.
+
+.. code-block:: rst
+
+    .. glossary::
+        :sorted:
+
+        voom
+            Theoretically, the sound a parrot makes when four-thousand volts of electricity pass through it.
+
+        pining
+            What the Norwegien Blue does when it misses its homeland, e.g., pining for the fjords.
+
+The above code renders as follows.
+
+.. glossary::
+    :sorted:
+
+    voom
+        Theoretically, the sound a parrot makes when four-thousand volts of electricity pass through it.
+
+    pining
+        What the Norwegien Blue does when it misses its homeland, e.g., pining for the fjords.
+
+References to glossary terms use the ``term`` directive.
+
+.. code-block:: rst
+
+    :term:`voom`
+
+The above code renders as follows. Note it is hyperlinked, and when clicked it will take the user to the term in the Glossary and highlight the term.
+
+:term:`voom`
 
 
 .. _style-guide-section-structure:
@@ -54,9 +164,9 @@ Section structure
 
 Each section, or a subdirectory of reST files, such as a tutorial, must contain an ``index.rst`` file. ``index.rst`` must contain the following.
 
-- A section heading. This will be visible in the table of contents.
-- A single paragraph describing this section.
-- A Sphinx ``toctree`` directive, with a ``maxdepth`` of 2. Each ``.rst`` file in the folder should be linked to this ``toctree``.
+* A section heading. This will be visible in the table of contents.
+* A single paragraph describing this section.
+* A Sphinx ``toctree`` directive, with a ``maxdepth`` of 2. Each ``.rst`` file in the folder should be linked to this ``toctree``.
 
     .. code-block:: rst
 
@@ -75,7 +185,7 @@ Page structure
 
 Each page should contain in order the following.
 
-- The main heading. This will be visible in the table of contents.
+#. The main heading. This will be visible in the table of contents.
 
     .. code-block:: rst
 
@@ -83,17 +193,22 @@ Each page should contain in order the following.
         The main heading
         ================
 
-- The description of the page. This text will be displayed to the reader below the main heading as well as be inserted into the description metadata field of the document. It will be displayed in search engine listings for the page. This is created using the reST ``admonition`` directive. A single paragraph of text consisting of no more than three sentences is recommended, so that the same text fits into search engine results:
+#. Meta tag information. The "meta" directive is used to specify HTML metadata stored in HTML META tags. "Metadata" is data about data, in this case data about web pages. Metadata is used to describe and classify web pages in the World Wide Web, in a form that is easy for search engines to extract and collate.
 
     .. code-block:: rst
 
-        .. admonition:: description
+        .. meta::
+           :description: This chapter describes how to edit, update, and build the Pyramid documentation.
+           :keywords: Pyramid, Style Guide
 
-           This is a description of the page, which will appear inline and in the description metadata field.
+    The above code renders as follows.
 
-    .. note:: The ``description`` metadata field is not yet implemented in the documentation's Sphinx theme, but it is a `feature request <https://github.com/Pylons/pylons_sphinx_theme/wiki/New-Theme-Requests>`_, so it is helpful to start using the ``description`` admonition now.
+    .. code-block:: xml
 
-- Introduction paragraph.
+        <meta content="This chapter describes how to edit, update, and build the Pyramid documentation." name="description" />
+        <meta content="Pyramid, Style Guide" name="keywords" />
+
+#. Introduction paragraph.
 
     .. code-block:: rst
 
@@ -102,7 +217,7 @@ Each page should contain in order the following.
 
         This chapter is an introduction.
 
-- Finally the content of the document page, consisting of reST elements such as headings, paragraphs, tables, and so on.
+#. Finally the content of the document page, consisting of reST elements such as headings, paragraphs, tables, and so on.
 
 
 .. _style-guide-page-content:
@@ -126,8 +241,8 @@ Narrative documentation is not code, and should therefore not adhere to PEP8 or
 Trailing white spaces
 ^^^^^^^^^^^^^^^^^^^^^
 
-- No trailing white spaces.
-- Always use a line feed or carriage return at the end of a file.
+* No trailing white spaces.
+* Always use a line feed or carriage return at the end of a file.
 
 
 .. _style-guide-indentation:
@@ -135,8 +250,8 @@ Trailing white spaces
 Indentation
 ^^^^^^^^^^^
 
-- Indent using four spaces.
-- Do not use tabs to indent.
+* Indent using four spaces.
+* Do not use tabs to indent.
 
 
 .. _style-guide-grammar-spelling-preferences:
@@ -144,7 +259,7 @@ Indentation
 Grammar, spelling, and capitalization preferences
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Use any commercial or free professional style guide in general. Use a spell- and grammar-checker. The following table lists the preferred grammar, spelling, and capitalization of words and phrases for frequently used items in the documentation.
+Use any commercial or free professional style guide in general. Use a spell* and grammar-checker. The following table lists the preferred grammar, spelling, and capitalization of words and phrases for frequently used items in the documentation.
 
 ========== =====
 Preferred  Avoid
@@ -169,10 +284,10 @@ Capitalize only the first letter in a heading (sentence-case), unless other word
 
 For consistent heading characters throughout the documentation, follow the guidelines stated in the `Python Developer's Guide <https://docs.python.org/devguide/documenting.html#sections>`_. Specifically:
 
-- =, for sections
-- -, for subsections
-- ^, for subsubsections
-- ", for paragraphs
+* =, for sections
+* -, for subsections
+* ^, for subsubsections
+* ", for paragraphs
 
 As individual files do not have so-called "parts" or "chapters", the headings would be underlined with characters as shown.
 
@@ -227,35 +342,7 @@ The above code renders as follows.
 
 `TryPyramid <https://TryPyramid.com>`_
 
-To link to pages within this documentation:
-
-.. code-block:: rst
-
-    :doc:`quick_tour`
-
-The above code renders as follows.
-
-:doc:`quick_tour`
-
-To link to a section within a page in this documentation:
-
-.. code-block:: rst
-
-    :ref:`quick_tour`
-
-The above code renders as follows.
-
-:ref:`quick_tour`
-
-To link to pages configured via intersphinx:
-
-.. code-block:: rst
-
-    :ref:`Deform <deform:overview>`
-
-The above code renders as follows.
-
-:ref:`Deform <deform:overview>`
+.. seealso:: See also :ref:`style-guide-cross-references` for generating links throughout the entire documentation.
 
 
 .. _style-guide-topic:
@@ -290,7 +377,7 @@ Displaying code
 
 Code may be displayed in blocks or inline. You can include blocks of code from other source files. Blocks of code should use syntax highlighting.
 
-.. seealso:: See also the Sphinx documentation for :ref:`Showing code examples <sphinx:code-examples>`.
+.. seealso:: See also the Sphinx documentation for :ref:`code-examples`.
 
 
 .. _style-guide-syntax-highlighting:
@@ -378,6 +465,26 @@ If syntax highlighting is not enabled for your code block, you probably have a s
 View the `full list of lexers and associated short names <http://pygments.org/docs/lexers/>`_.
 
 
+.. _style-guide-parsed-literals:
+
+Parsed literals
+```````````````
+
+Parsed literals are used to render, for example, a specific version number of the application in code blocks. Use the directive ``parsed-literal``. Note that syntax highlighting is not supported and code is rendered as plain text.
+
+.. code-block:: rst
+
+    .. parsed-literal::
+
+        $ $VENV/bin/pip install "pyramid==\ |release|\ "
+
+The above code renders as follows.
+
+.. parsed-literal::
+
+    $ $VENV/bin/pip install "pyramid==\ |release|\ "
+
+
 .. _style-guide-long-commands:
 
 Displaying long commands
@@ -500,10 +607,10 @@ The above code renders as follows.
 
 Like code blocks, ``literalinclude`` supports the following options.
 
-- ``language`` to select a language for syntax highlighting
-- ``linenos`` to switch on line numbers
-- ``lineno-start`` to specify the starting number to use for line numbering
-- ``emphasize-lines`` to emphasize particular lines
+* ``language`` to select a language for syntax highlighting
+* ``linenos`` to switch on line numbers
+* ``lineno-start`` to specify the starting number to use for line numbering
+* ``emphasize-lines`` to emphasize particular lines
 
 .. code-block:: rst
 
@@ -681,9 +788,9 @@ Simple tables require less markup but have fewer features and some constraints c
     1      Second column of row 1.
     2      Second column of row 2.
            Second line of paragraph.
-    3      - Second column of row 3.
+    3      * Second column of row 3.
 
-           - Second item in bullet
+           * Second item in bullet
              list (row 3, column 2).
     \      Row 4; column 1 will be empty.
     =====  =====
@@ -696,9 +803,9 @@ col 1  col 2
 1      Second column of row 1.
 2      Second column of row 2.
        Second line of paragraph.
-3      - Second column of row 3.
+3      * Second column of row 3.
 
-       - Second item in bullet
+       * Second item in bullet
          list (row 3, column 2).
 \      Row 4; column 1 will be empty.
 =====  =====
@@ -715,9 +822,9 @@ Grid tables have much more cumbersome markup, although Emacs' table mode may les
     +------------------------+------------+----------+----------+
     | body row 2             | Cells may span columns.          |
     +------------------------+------------+---------------------+
-    | body row 3             | Cells may  | - Table cells       |
-    +------------------------+ span rows. | - contain           |
-    | body row 4             |            | - body elements.    |
+    | body row 3             | Cells may  | * Table cells       |
+    +------------------------+ span rows. | * contain           |
+    | body row 4             |            | * body elements.    |
     +------------------------+------------+---------------------+
 
 The above code renders as follows.
@@ -730,18 +837,82 @@ The above code renders as follows.
 +------------------------+------------+----------+----------+
 | body row 2             | Cells may span columns.          |
 +------------------------+------------+---------------------+
-| body row 3             | Cells may  | - Table cells       |
-+------------------------+ span rows. | - contain           |
-| body row 4             |            | - body elements.    |
+| body row 3             | Cells may  | * Table cells       |
++------------------------+ span rows. | * contain           |
+| body row 4             |            | * body elements.    |
 +------------------------+------------+---------------------+
 
 
-.. _style-guide-danger-errors:
+.. _style-guide-feature-versioning:
+
+Feature versioning
+^^^^^^^^^^^^^^^^^^
+
+Three directives designate the version in which something is added, changed, or deprecated in the project.
+
+
+.. _style-guide-version-added:
+
+Version added
+`````````````
 
-Danger and errors
-^^^^^^^^^^^^^^^^^
+To indicate the version in which a feature is added to a project, use the ``versionadded`` directive. If the feature is an entire module, then the directive should be placed at the top of the module section before any prose.
 
-Danger and errors represent critical information related to a topic or concept, and should recommend to the user "don't do this dangerous thing". ``danger`` and ``error`` appear similarly when rendered, but the HTML generated has the appropriate semantic context.
+The first argument is the version. An optional second argument must appear upon a subsequent line, without blank lines in between, and indented.
+
+.. code-block:: rst
+
+    .. versionadded:: 1.1
+        :func:`pyramid.paster.bootstrap`
+
+The above code renders as follows.
+
+.. versionadded:: 1.1
+    :func:`pyramid.paster.bootstrap`
+
+
+.. _style-guide-version-changed:
+
+Version changed
+```````````````
+
+To indicate the version in which a feature is changed in a project, use the ``versionchanged`` directive. Its arguments are the same as ``versionadded``.
+
+.. code-block:: rst
+
+    .. versionchanged:: 1.8
+        Added the ability for ``bootstrap`` to cleanup automatically via the ``with`` statement.
+
+The above code renders as follows.
+
+.. versionchanged:: 1.8
+    Added the ability for ``bootstrap`` to cleanup automatically via the ``with`` statement.
+
+
+.. _style-guide-deprecated:
+
+Deprecated
+``````````
+
+Similar to ``versionchanged``, ``deprecated`` describes when the feature was deprecated. An explanation can also be given, for example, to inform the reader what should be used instead.
+
+.. code-block:: rst
+
+    .. deprecated:: 1.7
+        Use the ``require_csrf`` option or read :ref:`auto_csrf_checking` instead to have :class:`pyramid.exceptions.BadCSRFToken` exceptions raised.
+
+The above code renders as follows.
+
+.. deprecated:: 1.7
+    Use the ``require_csrf`` option or read :ref:`auto_csrf_checking` instead to have :class:`pyramid.exceptions.BadCSRFToken` exceptions raised.
+
+
+.. _style-guide-danger:
+
+Danger
+^^^^^^
+
+Danger represents critical information related to a topic or concept, and should recommend to the user "don't do this dangerous thing".
 
 .. code-block:: rst
 
@@ -800,6 +971,26 @@ The above code renders as follows.
     This is a note.
 
 
+.. _style-guide-see-also:
+
+See also
+^^^^^^^^
+
+"See also" messages refer to topics that are related to the current topic, but have a narrative tone to them instead of merely a link without explanation. "See also" is rendered in a block as well, so that it stands out for the reader's attention.
+
+.. code-block:: rst
+
+    .. seealso::
+
+        See :ref:`Quick Tutorial section on Requirements <qtut_requirements>`.
+
+The above code renders as follows.
+
+.. seealso::
+
+    See :ref:`Quick Tutorial section on Requirements <qtut_requirements>`.
+
+
 .. _style-guide-todo:
 
 Todo
@@ -871,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.
+
+: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.
 
-.. _style-guide-python:
+.. 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.
 
@@ -917,35 +1171,99 @@ The above code renders as follows.
 
 :func:`pyramid.renderers.render_to_response`
 
-.. seealso::
+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.
 
-    See also the Sphinx documentation for the :ref:`reStructuredText Primer <sphinx:rst-primer>`.
+.. code-block:: rst
 
+    :func:`~.render_to_response`
 
+The above code renders as follows.
 
-:app:`Pyramid`
+:func:`~.render_to_response`
 
-:ref:`i18n_chapter`
 
-References to glossary terms are presented using the following style:
+.. _style-guide-role-app-pyramid:
 
-  :term:`Pylons`
+The role ``:app:`Pyramid```
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Glossary terms appear in the Glossary
+We use the special role ``app`` to refer to the application "Pyramid".
 
-.. glossary:: :sorted:
 
-References to sections and chapters are presented using the following style:
+.. code-block:: rst
+
+    :app:`Pyramid`
 
-  :ref:`traversal_chapter`
+The above code renders as follows.
 
+:app:`Pyramid`
 
-API documentation
+
+.. _style-guide-sphinx-extensions:
+
+Sphinx extensions
 -----------------
 
-.. automodule:: pyramid.i18n
+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.
+
 
-.. .. autoclass:: TranslationString
+.. _style-guide-sphinx-extension-autodoc:
 
-.. .. autofunction:: TranslationStringFactory
+:mod:`sphinx.ext.autodoc`
+-------------------------
+
+API documentation uses the Sphinx extension :mod:`sphinx.ext.autodoc` to include documentation from docstrings.
+
+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>`.
+
+
+.. _style-guide-sphinx-extension-doctest:
+
+:mod:`sphinx.ext.doctest`
+-------------------------
+
+: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``.
+
+
+.. _style-guide-sphinx-extension-intersphinx:
+
+:mod:`sphinx.ext.intersphinx`
+-----------------------------
+
+:mod:`sphinx.ext.intersphinx` generates links to the documentation of objects in other projects.
+
+
+.. _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.
+
+
+.. _style-guide-sphinx-extension-repoze-sphinx-autointerface:
+
+`repoze.sphinx.autointerface <https://pypi.python.org/pypi/repoze.sphinx.autointerface>`_
+-----------------------------------------------------------------------------------------
+
+`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.