Merge pull request #2828 from stevepiercy/style-guide

More style guide updates

2 files changed, 363 insertions, 84 deletions

diff --git a/docs/conf.py b/docs/conf.py
index c3a7170fc..ace921247 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -68,6 +68,7 @@ intersphinx_mapping = {
     'pylonswebframework': ('http://docs.pylonsproject.org/projects/pylons-webframework/en/latest/', None),
     'python': ('https://docs.python.org/3', None),
     'pytest': ('http://pytest.org/latest/', None),
+    'sphinx': ('http://www.sphinx-doc.org/en/latest', None),
     'sqla': ('http://docs.sqlalchemy.org/en/latest', None),
     'tm': ('http://docs.pylonsproject.org/projects/pyramid-tm/en/latest/', None),
     'toolbar': ('http://docs.pylonsproject.org/projects/pyramid-debugtoolbar/en/latest', None),
diff --git a/docs/style-guide.rst b/docs/style-guide.rst
index 3f2b630d3..c30b199a6 100644
--- a/docs/style-guide.rst
+++ b/docs/style-guide.rst
@@ -5,7 +5,7 @@ Style Guide
 
 .. admonition:: description
 
-   This chapter describes how to edit, update, and build the :app:`Pyramid` documentation.
+   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>`_.
 
 
 .. _style-guide-introduction:
@@ -47,6 +47,27 @@ Location, referencing, and naming of files
   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-section-structure:
+
+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``.
+
+    .. code-block:: rst
+
+        .. toctree::
+           :maxdepth: 2
+
+           chapter1
+           chapter2
+           chapter3
+
+
 .. _style-guide-page-structure:
 
 Page structure
@@ -84,10 +105,18 @@ Each page should contain in order the following.
 - Finally the content of the document page, consisting of reST elements such as headings, paragraphs, tables, and so on.
 
 
+.. _style-guide-page-content:
+
+Page content
+------------
+
+Within a page, content should adhere to specific guidelines.
+
+
 .. _style-guide-line-lengths:
 
 Line lengths
-------------
+^^^^^^^^^^^^
 
 Narrative documentation is not code, and should therefore not adhere to PEP8 or other line length conventions. When a translator sees only part of a sentence or paragraph, it makes it more difficult to translate the concept. Line lengths make ``diff`` more difficult. Text editors can soft wrap lines for display to avoid horizontal scrolling. We admit, we boofed it by using arbitrary 79-character line lengths in our own documentation, but we have seen the error of our ways and wish to correct this going forward.
 
@@ -95,7 +124,7 @@ Narrative documentation is not code, and should therefore not adhere to PEP8 or
 .. _style-guide-trailing-white-space:
 
 Trailing white spaces
----------------------
+^^^^^^^^^^^^^^^^^^^^^
 
 - No trailing white spaces.
 - Always use a line feed or carriage return at the end of a file.
@@ -104,153 +133,402 @@ Trailing white spaces
 .. _style-guide-indentation:
 
 Indentation
------------
+^^^^^^^^^^^
 
 - Indent using four spaces.
 - Do not use tabs to indent.
 
 
+.. _style-guide-grammar-spelling-preferences:
+
+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.
+
+========== ======================
+Preferred  Avoid
+========== ======================
+add-on     addon
+and so on  etc.
+GitHub     Github, github
+JavaScript Javascript, javascript
+plug-in    plugin
+select     check, tick (checkbox)
+such as    like
+verify     be sure
+========== ======================
+
+
 .. _style-guide-headings:
 
 Headings
---------
+^^^^^^^^
+
+Capitalize only the first letter in a heading (sentence-case), unless other words are proper nouns or acronyms, e.g., "Pyramid" or "HTML".
+
+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:
 
-Capitalize only the first letter in a heading, unless other words are proper nouns or acronyms, e.g., "Pyramid" or "HTML".
+- =, 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.
+
+    .. code-block:: rst
 
+        Heading Level 1
+        ===============
+
+        Heading Level 2
+        ---------------
+
+        Heading Level 3
+        ^^^^^^^^^^^^^^^
+
+        Heading Level 4
+        ```````````````
 
 .. _style-guide-paragraphs:
 
 Paragraphs
-----------
+^^^^^^^^^^
 
 A paragraph should be on one line. Paragraphs must be separated by two line feeds.
 
 
-.. _style-guide-grammar-spelling-preferences:
+.. _style-guide-links:
 
-Grammar, spelling, and capitalization preferences
--------------------------------------------------
+Links
+^^^^^
 
-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 inline links to keep the context or link label together with the URL. Do not use targets and links at the end of the page, because the separation makes it difficult to update and translate. Here is an example of inline links, our required method.
 
-==========           ======================
-Preferred            Avoid
-==========           ======================
-add-on	             addon
-and so on	         etc.
-GitHub	             Github, github
-JavaScript	         Javascript, javascript
-plug-in	             plugin
-select	             check, tick (checkbox)
-such as	             like
-verify	             be sure
-==========           ======================
+    .. code-block:: rst
 
+        `Example <http://example.com>`_
 
 
+.. _style-guide-topic:
 
+Topic
+^^^^^
 
-Literals, filenames, and function arguments are presented using the
-following style:
+A topic is similar to a block quote with a title, or a self-contained section with no subsections. Use the ``topic`` directive to indicate a self-contained idea that is separate from the flow of the document. Topics may occur anywhere a section or transition may occur. Body elements and topics may not contain nested topics.
 
-  ``argument1``
+The directive's sole argument is interpreted as the topic title, and next line must be blank. All subsequent lines make up the topic body, interpreted as body elements.
 
-Warnings which represent limitations and need-to-know information
-related to a topic or concept are presented in the following style:
+    .. code-block:: rst
 
-  .. warning::
+        .. topic:: Topic Title
 
-     This is a warning.
+            Subsequent indented lines comprise
+            the body of the topic, and are
+            interpreted as body elements.
 
-Notes which represent additional information related to a topic or
-concept are presented in the following style:
 
-  .. note::
+.. _style-guide-displaying-code:
 
-     This is a note.
+Displaying code
+^^^^^^^^^^^^^^^
 
-We present Python method names using the following style:
+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.
 
-  :meth:`pyramid.config.Configurator.add_view`
+.. seealso:: See also the Sphinx documentation for :ref:`Showing code examples <sphinx:code-examples>`.
 
-We present Python class names, module names, attributes, and global
-variables using the following style:
 
-  :class:`pyramid.config.Configurator.registry`
+.. _style-guide-syntax-highlighting:
 
-References to glossary terms are presented using the following style:
+Syntax highlighting
+```````````````````
 
-  :term:`Pylons`
+Sphinx does syntax highlighting of code blocks using the `Pygments <http://pygments.org/>`_ library.
 
-URLs are presented using the following style:
+Do not use two colons "::" at the end of a line, followed by a blank line, then indented code. Always specify the language to be used for syntax highlighting by using the ``code-block`` directive and indenting the code.
 
-  `Pylons <http://www.pylonsproject.org>`_
+    .. code-block:: rst
 
-References to sections and chapters are presented using the following
-style:
+        .. code-block:: python
 
-  :ref:`traversal_chapter`
+            if "foo" == "bar":
+                # This is Python code
+                pass
 
-Code and configuration file blocks are presented in the following style:
+XML:
 
-  .. code-block:: python
-     :linenos:
+    .. code-block:: rst
 
-     def foo(abc):
-         pass
+        .. code-block:: xml
 
-Example blocks representing UNIX shell commands are prefixed with a ``$``
-character, e.g.:
+            <somesnippet>Some XML</somesnippet>
 
-  .. code-block:: bash
+Unix shell commands are prefixed with a ``$`` character. (See :term:`venv` for the meaning of ``$VENV``.)
 
-     $ $VENV/bin/py.test -q
+    .. code-block:: rst
+
+        .. code-block:: bash
+
+           $ $VENV/bin/pip install -e .
+
+Windows commands are prefixed with a drive letter with an optional directory name. (See :term:`venv` for the meaning of ``%VENV%``.)
+
+    .. code-block:: rst
 
-See :term:`venv` for the meaning of ``$VENV``.
+        .. code-block:: doscon
 
-Example blocks representing Windows commands are prefixed with a drive letter
-with an optional directory name, e.g.:
+           c:\> %VENV%\Scripts\pcreate -s starter MyProject
 
   .. code-block:: doscon
 
-     c:\examples> %VENV%\Scripts\py.test -q
+cfg:
+
+    .. code-block:: rst
+
+        .. code-block:: cfg
+
+           [some-part]
+           # A random part in the buildout
+           recipe = collective.recipe.foo
+           option = value
+
+ini:
+
+    .. code-block:: rst
+
+        .. code-block:: ini
+
+            [nosetests]
+            match=^test
+            where=pyramid
+            nocapture=1
+
+Interactive Python:
+
+    .. code-block:: rst
+
+        .. code-block:: pycon
+
+           >>> class Foo:
+           ...     bar = 100
+           ...
+           >>> f = Foo()
+           >>> f.bar
+           100
+           >>> f.bar / 0
+           Traceback (most recent call last):
+             File "<stdin>", line 1, in <module>
+           ZeroDivisionError: integer division or modulo by zero
+
+If syntax highlighting is not enabled for your code block, you probably have a syntax error and Pygments will fail silently.
+
+View the `full list of lexers and associated short names <http://pygments.org/docs/lexers/>`_.
+
+
+.. _style-guide-long-commands:
+
+Displaying long commands
+````````````````````````
+
+When a command that should be typed on one line is too long to fit on the displayed width of a page, the backslash character ``\`` is used to indicate that the subsequent printed line should be part of the command:
+
+    .. code-block:: rst
+
+        .. code-block:: bash
+
+            $ $VENV/bin/py.test tutorial/tests.py --cov-report term-missing \
+                --cov=tutorial -q
+
+
+.. _style-guide-code-block-options:
+
+Code block options
+``````````````````
+
+To emphasize lines (give the appearance that a highlighting pen has been used on the code), use the ``emphasize-lines`` option. The argument passed to ``emphasize-lines`` must be a comma-separated list of either single or ranges of line numbers.
+
+.. code-block:: rst
+
+    .. code-block:: python
+        :emphasize-lines: 1,3
+
+        if "foo" == "bar":
+            # This is Python code
+            pass
 
-See :term:`venv` for the meaning of ``%VENV%``.
+The above code renders as follows.
 
-When a command that should be typed on one line is too long to fit on a page,
-the backslash ``\`` is used to indicate that the following printed line should
-be part of the command:
+.. code-block:: python
+    :emphasize-lines: 1,3
 
-  .. code-block:: bash
+    if "foo" == "bar":
+        # This is Python code
+        pass
 
-     $VENV/bin/py.test tutorial/tests.py --cov-report term-missing \
-                       --cov=tutorial -q
+To display a code block with line numbers, use the ``linenos`` option.
 
-A sidebar, which presents a concept tangentially related to content discussed
-on a page, is rendered like so:
+.. code-block:: rst
 
-.. sidebar:: This is a sidebar
+    .. code-block:: python
+        :linenos:
+
+        if "foo" == "bar":
+            # This is Python code
+            pass
+
+The above code renders as follows.
 
-   Sidebar information.
+.. code-block:: python
+    :linenos:
 
-When multiple objects are imported from the same package, the following
-convention is used:
+    if "foo" == "bar":
+        # This is Python code
+        pass
+
+Code blocks may be given a caption, which may serve as a filename or other description, using the ``caption`` option. They may also be given a ``name`` option, providing an implicit target name that can be referenced by using ``ref``.
+
+.. code-block:: rst
 
     .. code-block:: python
+        :caption: sample.py
+        :name: sample-py
+
+        if "foo" == "bar":
+            # This is Python code
+            pass
+
+The above code renders as follows.
+
+.. code-block:: python
+    :caption: sample.py
+    :name: sample-py
+
+    if "foo" == "bar":
+        # This is Python code
+        pass
+
+To specify the starting number to use for line numbering, use the ``lineno-start`` directive.
+
+.. code-block:: rst
+
+    .. code-block:: python
+        :lineno-start: 2
+
+        if "foo" == "bar":
+            # This is Python code
+            pass
+
+The above code renders as follows. As you can see, ``lineno-start`` is not altogether meaningful.
+
+.. code-block:: python
+    :lineno-start: 2
+
+    if "foo" == "bar":
+        # This is Python code
+        pass
+
+
+.. _style-guide-includes:
+
+Includes
+````````
+
+Longer displays of verbatim text may be included by storing the example text in an external file containing only plain text or code. The file may be included using the ``literalinclude`` directive. The file name follows the conventions of :ref:`style-guide-file-conventions`.
+
+.. code-block:: rst
+
+    .. literalinclude:: narr/helloworld.py
+        :language: python
+
+The above code renders as follows.
+
+.. literalinclude:: narr/helloworld.py
+    :language: python
+
+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
+
+.. code-block:: rst
+
+    .. literalinclude:: narr/helloworld.py
+        :language: python
+        :linenos:
+        :lineno-start: 11
+        :emphasize-lines: 1,6-7,9-
+
+The above code renders as follows. Note that ``lineno-start`` and ``emphasize-lines`` do not align.  The former displays numbering starting from the *arbitrarily provided value*, whereas the latter emphasizes the line numbers of the *source file*.
+
+.. literalinclude:: narr/helloworld.py
+    :language: python
+    :linenos:
+    :lineno-start: 11
+    :emphasize-lines: 1,6-7,9-
+
+Additional options include the following.
 
-       from foo import (
-           bar,
-           baz,
-           )
+.. literalinclude:: narr/helloworld.py
+    :lines: 1-3
+    :emphasize-lines: 3
+    :lineno-match:
+    :language: python
 
-It may look unusual, but it has advantages:
+.. literalinclude:: narr/helloworld.py
+    :linenos:
+    :pyobject: hello_world
 
-- It allows one to swap out the higher-level package ``foo`` for something else
-  that provides the similar API. An example would be swapping out one database
-  for another (e.g., graduating from SQLite to PostgreSQL).
+.. literalinclude:: quick_tour/sqla_demo/sqla_demo/models/mymodel.py
+    :language: python
+    :start-after: Start Sphinx Include
+    :end-before: End Sphinx Include
 
-- Looks more neat in cases where a large number of objects get imported from
-  that package.
 
-- Adding or removing imported objects from the package is quicker and results
-  in simpler diffs.
+.. _style-guide-inline-code:
+
+Inline code
+```````````
+
+
+
+
+
+
+Literals, filenames, and function arguments are presented using the
+following style:
+
+  ``argument1``
+
+Warnings which represent limitations and need-to-know information
+related to a topic or concept are presented in the following style:
+
+  .. warning::
+
+     This is a warning.
+
+Notes which represent additional information related to a topic or
+concept are presented in the following style:
+
+  .. note::
+
+     This is a note.
+
+We present Python method names using the following style:
+
+  :meth:`pyramid.config.Configurator.add_view`
+
+We present Python class names, module names, attributes, and global
+variables using the following style:
+
+  :class:`pyramid.config.Configurator.registry`
+
+References to glossary terms are presented using the following style:
+
+  :term:`Pylons`
+
+References to sections and chapters are presented using the following
+style:
+
+  :ref:`traversal_chapter`