path: root/docs/style-guide.rst

.. _style-guide:

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>`_.


.. _style-guide-introduction:

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.


.. _style-guide-contribute:

How to update and contribute to documentation
---------------------------------------------

All projects under the Pylons Projects, including this one, follow the guidelines established at `How to Contribute <http://www.pylonsproject.org/community/how-to-contribute>`_ and `Coding Style and Standards <http://docs.pylonsproject.org/en/latest/community/codestyle.html>`_.

By building the documentation locally, you can preview the output before committing and pushing your changes to the repository. Follow the instructions for `Building documentation for a Pylons Project project <https://github.com/Pylons/pyramid/blob/master/contributing.md#building-documentation-for-a-pylons-project-project>`_. These instructions also include how to install packages required to build the documentation, and how to follow our recommended git workflow.

When submitting a pull request for the first time in a project, sign `CONTRIBUTORS.txt <https://github.com/Pylons/pyramid/blob/master/CONTRIBUTORS.txt>`_ and commit it along with your pull request.


.. _style-guide-file-conventions:

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:

  .. code-block:: rst

     .. 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).


.. _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
--------------

Each page should contain in order the following.

- The main heading. This will be visible in the table of contents.

    .. code-block:: rst

        ================
        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:

    .. code-block:: rst

        .. admonition:: description

           This is a description of the page, which will appear inline and in the description metadata field.

    .. 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.

- Introduction paragraph.

    .. code-block:: rst

        Introduction
        ------------

        This chapter is an introduction.

- 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.


.. _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.


.. _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:

- =, 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-links:

Links
^^^^^

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.

    .. code-block:: rst

        `Example <http://example.com>`_


.. _style-guide-topic:

Topic
^^^^^

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.

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.

    .. code-block:: rst

        .. topic:: Topic Title

            Subsequent indented lines comprise
            the body of the topic, and are
            interpreted as body elements.


.. _style-guide-displaying-code:

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>`.


.. _style-guide-syntax-highlighting:

Syntax highlighting
```````````````````

Sphinx does syntax highlighting of code blocks using the `Pygments <http://pygments.org/>`_ library.

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.

    .. code-block:: rst

        .. code-block:: python

            if "foo" == "bar":
        # This is Python         code
        pass

        XML:

    .. code-block:: rst

        .. code-block:: xml

            <somesnippet>Some XML</somesnippet>

Unix shell commands are prefixed with a ``$`` character. (See :term:`venv` for the meaning of ``$VENV``.)

    .. 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

        .. code-block:: doscon

           c:\> %VENV%\Scripts\pcreate -s starter MyProject

  .. code-block:: doscon

cfg:

    .. code-block:: rst

        .. code-block:: cfg

           [some-part]
   # A random part in         the buildout
   recipe = collectiv        e.recipe.foo
   option = value

        ini:

    .. code-block:: rst

        .. code-block:: ini

            [nosetests]
    match=^test
    w        here=pyramid
            nocapture=1

        Interactive Python:

    .. code-block:: rst

        .. code-block:: pycon

           >>> class Foo:
   ...     bar = 100
           ...
   >>> f = Foo()        
   >>>         f.bar
   100
           >>> f.bar / 0        
   Tra        ceback (most rece        nt call last):
     File "<stdin>", li        ne 1, in <module>
   ZeroDivisionError: i        nteger 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

The above code renders as follows.

.. code-block:: python
    :emphasize-lines: 1,3

    if "foo" == "bar":
        # This is Python code
        pass

To display a code block with line numbers, use the ``linenos`` option.

.. code-block:: rst

    .. code-block:: python
        :linenos:

        if "foo" == "bar":
            # This is Python code
            pass

The above code renders as follows.

.. code-block:: python
    :linenos:

    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.

.. literalinclude:: narr/helloworld.py
    :lines: 1-3
    :emphasize-lines: 3
    :lineno-match:
    :language: python

.. literalinclude:: narr/helloworld.py
    :linenos:
    :pyobject: hello_world

.. literalinclude:: quick_tour/sqla_demo/sqla_demo/models/mymodel.py
    :language: python
    :start-after: Start Sphinx Include
    :end-before: End Sphinx Include


.. _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`