Pylons Project Documentation Style Guide

Introduction

This document is aimed at authors of and contributors to documentation for projects under the Pylons Project. This document describes style and reStructuredText syntax used in project documentation. We provide examples, including reStructuredText code and its rendered output, for both visual and technical reference.

The source code of this guide is located in its project repository on GitHub.

For Python coding style guidelines, see Coding Style.

We have adopted the convention from RFC 2119 for key words.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

Other conventions throughout this guide are adopted and adapted from Documenting Python, Plone Documentation Style Guide, and Write The Docs.

Contributing to a project's documentation

All projects under the Pylons Projects follow the guidelines established at How to Contribute.

When submitting a pull request for the first time in a project, sign its CONTRIBUTORS.txt and commit it along with your pull request.

Contributors to documentation should be familiar with reStructuredText (reST) for writing documentation. Most projects use Sphinx to build documentation from reST source files, and Read The Docs (RTD) for publishing them on the web. Experience with Sphinx and RTD may be helpful, but not required.

Testing Documentation

Before submitting a pull request, documentation should be tested locally. Ultimately testing of documentation must be done before merging a pull request. This is typically done through a project's integration with Travis CI or Appveyor.

  • Use Sphinx's make html command to build the HTML output of the documentation without errors or warnings. Some projects use tox -e docs or just tox to invoke Sphinx's make html. Most other build utilities like restview and readme_renderer test only a single file and do not support cross-references between files.
  • If documentation has doctests and uses sphinx.ext.doctest, then run Sphinx's make doctest command.
  • Optionally use Sphinx's make linkcheck command to verify that links are valid and to avoid bit rot. It is acceptable to ignore broken links in a project's change log and history. Narrative and API documentation should occasionally have its links checked.
  • Optionally use Sphinx's make epub and make latexpdf or make xelatex commands to build epub or PDF output of the documentation.

This project's repository has an example of how to configure Sphinx, tox, and Travis to build documentation.

Documentation structure

This section describes the structure of documentation and its files.

Location

Documentation source files should be contained in a folder named docs located at the root of the project. Images and other static assets should 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 naming

reST source files and static assets should have names that consist only of lowercase letters (a-z), numbers (0-9), periods (.), and hyphens (-) instead of underscores (_). Files must start a letter. reST source files should have the extension of .rst.

Image files may be any format, but must have standard file extensions that consist of three letters (.gif, .jpg, .png, .svg). .gif and .svg are not currently supported by PDF builders in Sphinx. However you can use an asterisk (*) as a wildcard extension instead of the actual file extension. This allows the Sphinx builder to automatically select the correct image format for the desired output. For example:

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

Index

Documentation must have an index file whose purpose is to serve as a home page for the documentation, including references to all other pages in the documentation. The index file should be named index.rst. Each section, or a subdirectory of reST files such as a tutorial, must contain an index.rst file.

The index should contain at least a Table of contents through the toctree directive.

The index should include a reference to both a search page and a general index page, which are automatically generated by Sphinx. See below for an example.

* :ref:`genindex`
* :ref:`search`

Glossary

Documentation may have a glossary file. If present, it must be named glossary.rst.

This file defines terms used throughout the documentation. 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.

Example:

.. 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, for example, pining for the fjords.

The above code renders as follows.

pining
What the Norwegian Blue does when it misses its homeland, for example, pining for the fjords.
voom
Theoretically, the sound a parrot makes when four-thousand volts of electricity pass through it.

References to glossary terms appear as follows.

:term:`voom`

voom

Note it is hyperlinked, and when clicked it will take the user to the term in the Glossary and highlight the term.

Change history

Either a reference to a change history log file in the project or its inclusion in the documentation should be present. Change history should include feature additions, deprecations, bug fixes, release dates and versions, and other significant changes to the project.

File encoding

All documentation source files must be in UTF-8 encoding to allow special characters, including em-dash () and tree diagram characters.

General guidance

This section describes the general voice, tone, and style that documentation should follow. It also includes things for authors to consider when writing to your audience.

Accessibility

Consider that your audience includes people who fall into the following groups:

  • People who do not use English as their first language (English language rules are insanely complex). According to our web statistics for docs.pylonsproject.org, about 36% of all readers of documentation under the Pylons Project do not use English as their first language. And only about 32% of all visitors are from the United States, United Kingdom, Canada, Australia, New Zealand, and Ireland.
  • Visually impaired readers (a comma makes a huge difference to a screen reader, adding a "breath", much like a musical breath symbol).
  • Readers who don't have college-level reading comprehension.
  • Folks with reading disabilities.

Voice

It is acceptable to address the reader as "you". This helps make documentation, especially tutorials, more approachable. "You" is also less formal than "the user".

Avoid sentence run-ons

Instead of using long sentences, consider breaking them into multiple shorter sentences. Long complicated sentences are more difficult to understand than shorter, clearer sentences. Consider that your audience is not familiar with your content. That is why they are reading your documentation.

Gender

Except for speaking for oneself, the author should avoid using pronouns that identify a specific gender. Neutral gender pronouns "they", "them", "their", "theirs", "it", and "its" are preferred. Never use the hideous and clumsy "he/she".

Style

Avoid hype and marketing.

Avoid words that can frustrate or discourage the reader if they are not able to complete or understand a concept. Such words include "simple", "just", "very", "easy", and their derivations. For example, "Simply run the command foo bar, and you're up and running!" will frustrate a user who has neither installed the requirements for foo nor configured it to execute bar.

English Syntax

Use proper spelling, grammar, and punctuation. English Language & Usage is a good resource.

Never use "and/or". If you cannot figure out whether you should use "and" or "or", and are tempted to use the lazy "and/or", then write the sentence so it is clear.

Avoid abbreviations. Spell out words.

Avoid "etc.", "e.g.", and "i.e.". They do not translate well or read well by screen readers for the visually impaired. It is lazy, and sounds pretentious. Writers seldom get the usage or punctuation right. Instead spell it out to their meanings of "and so on", "for example", and "in other words".

Documentation page structure

Each page should contain in order the following.

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

    ================
    The main heading
    ================
    
  2. Meta tag information. The "meta" directive is used to specify HTML metadata stored in HTML META tags. 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.

    .. meta::
       :description: This chapter describes how to edit, update, and build the Pyramid documentation.
       :keywords: Pyramid, Style Guide
    

    The above code renders as follows.

    <meta content="This chapter describes how to edit, update, and build the Pyramid documentation." name="description" />
    <meta content="Pyramid, Style Guide" name="keywords" />
    
  3. Introduction paragraph.

    Introduction
    ------------
    
    This chapter is an introduction.
    
  4. Finally the content of the document page, consisting of reST elements such as headings, paragraphs, tables, and so on.

Documentation page content

This section describes the content of documentation source files.

Use of whitespace

Narrative documentation is not code, and should therefore not adhere to PEP 8 standards or other line length conventions. There is no maximum line length. Lines should be the length of one sentence, without hard wraps. Lines should not end with white space.

When a paragraph contains more than one sentence, its sentences should be written one per line. This makes it easier to edit and find differences when updating documentation.

For example:

This is the first sentence in a paragraph.
This is the second sentence in a paragraph.

This is a new paragraph.

Which renders as follows.

This is the first sentence in a paragraph. This is the second sentence in a paragraph.

This is a new paragraph.

All indentation should be 4 spaces. Do not use tabs to indent.

Each section should have two trailing blank lines to separate it from the previous section. A section heading should have a blank line following its underline and before its content.

A line feed or carriage return should be used at the end of a file.

All other whitespace is defined by reST syntax.

Table of contents

toctree entries should exclude the file extension. For example:

.. toctree::
    :maxdepth: 2

    narr/introduction
    narr/install
    narr/firstapp

Headings

Chapter titles, sections, sub-sections, sub-sub-sections, and sub-sub-sub-sections within a chapter (usually a single reST file) are indicated with markup and are displayed as headings at various levels. Conventions are adopted from Documenting Python, Sections.

Headings are rendered in HTML as follows:

Heading Level underline/overline character HTML
Title * <h1>
Sections = <h2>
Sub-sections - <h3>
Sub-sub-sections ^ <h4>
Sub-sub-sub-sections " <h5>

The chapter title of this document, Documentation Style Guide, has the following reST code.

*************************
Documentation Style Guide
*************************

Chapter titles should be over- and underlined with asterisks (*).

The heading for this section, Documentation content, has the following reST code:

Documentation content
=====================

The heading for this sub-section, Headings, has the following reST code:

Headings
--------

Sub-sub-section, and sub-sub-sub-section headings are shown as follows.

Heading Level 4

This is a sub-sub-section.

Heading Level 4
^^^^^^^^^^^^^^^
Heading Level 5

This is a sub-sub-sub-section.

Heading Level 5
"""""""""""""""

Paragraphs

A paragraph of text looks exactly like this paragraph. Paragraphs must be separated by two line feeds.

Lists

All list items should have their text indented to start in the fifth column. This makes it easier for editors to maintain uniform indentation, especially for nested and definition lists.

Bulleted lists use syntax and display as follows. It is recommended to use asterisks (*) for each list item because they stand out better than hyphens (-) in the reST source.

*   This is an item in a bulleted list.
*   This is another item in a bulleted list.

    The second item supports paragraph markup.
  • This is an item in a bulleted list.

  • This is another item in a bulleted list.

    The second item supports paragraph markup.

Numbered lists use syntax and display as follows. Numbered lists should use a number sign followed by a period (#.) and will be numbered automatically. Avoid manually numbering lists, instead allowing Sphinx to do the numbering for you.

#.  This is an item in a numbered list.
#.  This is another item in a numbered list.
  1. This is an item in a numbered list.
  2. This is another item in a numbered list.

Nested lists use syntax and display as follows. The appearance of nested lists can be created by separating the child lists from their parent list by blank lines, and indenting four spaces.

#.  This is a list item in the parent list.
#.  This is another list item in the parent list.

    #.  This is a list item in the child list.
    #.  This is another list item in the child list.

#.  This is one more list item in the parent list.
  1. This is a list item in the parent list.
  2. This is another list item in the parent list.
    1. This is a list item in the child list.
    2. This is another list item in the child list.
  3. This is one more list item in the parent list.

Definition lists use syntax and display as follows.

term
    Definition of the term is indented.

    A definition may have paragraphs and other reST markup.

next term
    Next term definition.
term

Definition of the term is indented.

A definition may have paragraphs and other reST markup.

next term
Next term definition.

Images

To display images, use the image directive.

.. image:: /_static/pyramid_request_processing.*

Will render in HTML as the following.

_images/pyramid_request_processing.svg

Source code

Source code may be displayed in blocks or inline.

Code blocks

Blocks of code should use syntax highlighting and specify the language, and may use line numbering or emphasis. Avoid the use of two colons (::) at the end of a line, followed by a blank line, then code, because this may result in code parsing warnings (or worse, silent failures) and incorrect source code highlighting. Always indent the source code in a code block. Code blocks use the directive code-block. Its syntax is the following, where the Pygments lexer is the name of the language, with options indented on the subsequent lines.

.. code-block:: lexer
    :option:

See also

See also the Sphinx documentation for Showing code examples.

Syntax highlighting examples

Python:

.. code-block:: python

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

Renders as:

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

Shell commands should have no prefix character. They get in the way of copy-pasting commands, and often don't look right with syntax highlighting.

Bash:

.. code-block:: bash

    $VENV/bin/pip install -e .

Renders as:

$VENV/bin/pip install -e .

Windows:

.. code-block:: doscon

    %VENV%\Scripts\pserve development.ini

Renders as:

%VENV%\Scripts\pserve development.ini

XML:

.. code-block:: xml

    <somesnippet>Some XML</somesnippet>

Renders as:

<somesnippet>Some XML</somesnippet>

cfg:

.. code-block:: cfg

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

Renders as:

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

ini:

.. code-block:: ini

    [nosetests]
    match=^test
    where=pyramid
    nocapture=1

Renders as:

[nosetests]
match=^test
where=pyramid
nocapture=1

Interactive Python:

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

Renders as:

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

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

    $ $VENV/bin/py.test tutorial/tests.py --cov-report term-missing \
        --cov=tutorial -q

Renders as:

$ $VENV/bin/py.test tutorial/tests.py --cov-report term-missing \
    --cov=tutorial -q

Code block options

To emphasize lines, we give the appearance that a highlighting pen has been used on the code using the option emphasize-lines. The argument passed to emphasize-lines must be a comma-separated list of either single or ranges of line numbers.

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

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

Renders as:

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

A code block with line numbers.

.. code-block:: python
    :linenos:

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

Renders as:

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

Code blocks may be given a caption. They may also be given a name option, providing an implicit target name that can be referenced by using ref (see Cross-referencing arbitrary locations).

.. code-block:: python
    :caption: sample.py
    :name: sample-py-dsg

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

Renders as:

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:: python
    :lineno-start: 2

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

Renders as:

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

Include code blocks from external files

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

.. literalinclude:: src/helloworld.py
    :language: python

The above code renders as follows.

from wsgiref.simple_server import make_server
from pyramid.config import Configurator
from pyramid.response import Response


def hello_world(request):
    return Response('Hello %(name)s!' % request.matchdict)

if __name__ == '__main__':
    with Configurator() as config:
        config.add_route('hello', '/hello/{name}')
        config.add_view(hello_world, route_name='hello')
        app = config.make_wsgi_app()
    server = make_server('0.0.0.0', 8080, app)
    server.serve_forever()

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

Additionally literal includes support the following options:

  • pyobject to select a Python object to display
  • lines to select lines to display
  • lineno-match to match line numbers with the selected lines from the lines option
linenos and lineno-start issues

Avoid the use of linenos and lineno-start with literal includes.

.. literalinclude:: src/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.

11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
from wsgiref.simple_server import make_server
from pyramid.config import Configurator
from pyramid.response import Response


def hello_world(request):
    return Response('Hello %(name)s!' % request.matchdict)

if __name__ == '__main__':
    with Configurator() as config:
        config.add_route('hello', '/hello/{name}')
        config.add_view(hello_world, route_name='hello')
        app = config.make_wsgi_app()
    server = make_server('0.0.0.0', 8080, app)
    server.serve_forever()
pyobject

literalinclude also supports including only parts of a file.

If the source code is a Python module, you can select a class, function, or method to include using the pyobject option.

.. literalinclude:: src/helloworld.py
    :language: python
    :pyobject: hello_world

The above code renders as follows. It returns the function hello_world in the source file.

def hello_world(request):
    return Response('Hello %(name)s!' % request.matchdict)
start-after and end-before

Another way to control which part of the file is included is to use the start-after and end-before options (or only one of them). If start-after is given as a string option, only lines that follow the first line containing that string are included. If end-before is given as a string option, only lines that precede the first lines containing that string are included.

.. literalinclude:: src/helloworld.py
    :language: python
    :start-after: from pyramid.response import Response
    :end-before: if __name__ == '__main__':

The above code renders as follows.



def hello_world(request):
    return Response('Hello %(name)s!' % request.matchdict)

lines

You can specify exactly which lines to include by giving a lines option.

.. literalinclude:: src/helloworld.py
    :language: python
    :lines: 6-7

The above code renders as follows.

def hello_world(request):
    return Response('Hello %(name)s!' % request.matchdict)
lineno-match

When specifying particular parts of a file to display, it can be useful to display exactly which lines are being presented. This can be done using the lineno-match option.

.. literalinclude:: src/helloworld.py
    :language: python
    :lines: 6-7
    :lineno-match:

The above code renders as follows.

6
7
def hello_world(request):
    return Response('Hello %(name)s!' % request.matchdict)
Recommendations

Out of all the ways to include parts of a file, pyobject is the most preferred option because if you change your code and add or remove lines, you don't need to adjust line numbering, whereas with lines you would have to adjust. start-after and end-before are less desirable because they depend on source code not changing. Alternatively you can insert comments into your source code to act as the delimiters, but that just adds comments that have nothing to do with the functionality of your code.

Above all with includes, if you use line numbering, it's much preferred to use lineno-match over linenos with lineno-start because it "just works" without thinking and with less markup.

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.

.. parsed-literal::

    $VENV/bin/pip install "docs-style-guide==\ |release|\ "

The above code renders as follows.

$VENV/bin/pip install "docs-style-guide==1.0"
Inline code

Inline code is surrounded by double backtick marks.

Install requirements for building documentation: ``pip install -e ".[docs]"``

Renders as:

Install requirements for building documentation: pip install -e ".[docs]"

Feature versioning

Three directives designate the version in which something is added, changed, or deprecated in the project.

The first argument is the version. An optional second argument must appear upon a subsequent line, without blank lines in between, and indented.

Version added

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.

.. versionadded:: 1.1
    :func:`pyramid.paster.bootstrap`

Renders as:

New in version 1.1: pyramid.paster.bootstrap()

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.

.. versionchanged:: 1.8
    Added the ability for ``bootstrap`` to cleanup automatically via the ``with`` statement.

Renders as:

Changed in version 1.8: Added the ability for bootstrap to cleanup automatically via the with statement.

Deprecated

Similar to versionchanged, deprecated describes when the feature was deprecated. An explanation may be given to inform the reader what should be used instead.

.. deprecated:: 1.7
    Use the ``require_csrf`` option or read :ref:`auto_csrf_checking` instead to have :class:`pyramid.exceptions.BadCSRFToken` exceptions raised.

Renders as:

Deprecated since version 1.7: Use the require_csrf option or read Checking CSRF Tokens Automatically instead to have pyramid.exceptions.BadCSRFToken exceptions raised.

Admonitions

Admonitions are intended to bring special attention to the reader.

Danger

Danger represents critical information related to a topic or concept, and should recommend to the user "don't do this dangerous thing". Use the danger or error directive.

.. danger::

    This is danger or an error.

The above code renders as follows.

Danger

This is danger or an error.

Warnings

Warnings represent limitations and advice related to a topic or concept.

.. warning::

    This is a warning.

The above code renders as follows.

Warning

This is a warning.

Notes

Notes represent additional information related to a topic or concept.

.. note::

    This is a note.

The above code renders as follows.

Note

This is a note.

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.

.. seealso::

    See :ref:`Quick Tutorial section on Requirements <qtut_requirements>`.

The above code renders as follows.

Todo

Todo items designate tasks that require further work.

.. todo::

    This is a todo item.

This renders as the following.

Todo

This is a todo item.

To display a list of all todos in the entire documentation, use the todolist directive.

.. todolist::

In this document, the above renders as the following.

Todo

This is a todo item.

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/docs-style-guide/checkouts/latest/docs/index.rst, line 1390.)

Tables

Two forms of tables are supported, simple and grid.

Simple tables require less markup but have fewer features and some constraints compared to grid tables. The right-most column in simple tables is unbound to the length of the underline in the column header.

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

       * Second item in bullet
         list (row 3, column 2).
\      Row 4; column 1 will be empty.
=====  =====

Renders as:

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.
  • Second item in bullet list (row 3, column 2).
Row 4; column 1 will be empty.

Grid tables have much more cumbersome markup, although Emacs' table mode may lessen the tedium.

+------------------------+------------+----------+----------+
| Header row, column 1   | Header 2   | Header 3 | Header 4 |
| (header rows optional) |            |          |          |
+========================+============+==========+==========+
| body row 1, column 1   | column 2   | column 3 | column 4 |
+------------------------+------------+----------+----------+
| body row 2             | Cells may span columns.          |
+------------------------+------------+---------------------+
| body row 3             | Cells may  | * Table cells       |
+------------------------+ span rows. | * contain           |
| body row 4             |            | * body elements.    |
+------------------------+------------+---------------------+

The above code renders as follows.

Header row, column 1 (header rows optional) Header 2 Header 3 Header 4
body row 1, column 1 column 2 column 3 column 4
body row 2 Cells may span columns.
body row 3 Cells may span rows.
  • Table cells
  • contain
  • body elements.
body row 4

Topic

A topic is similar to a block quote with a title, or a self-contained section with no subsections. A topic indicates a self-contained idea that is separate from the flow of the document. Topics may occur anywhere a section or transition may occur. For example:

.. topic:: Topic Title

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

renders as:

Topic Title

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

Comments

Comments may appear in reST source, but they are not rendered to the output. Comments are intended for documentation authors.

.. This is a comment.

See also

See also comments in Source code.

Font styles

Italics

This *word* is italicized.

The above code renders as follows.

This word is italicized.

Strong

This **word** is in bold text.

The above code renders as follows.

This word is in bold text.

Keyboard symbols

Press :kbd:`Ctrl-C` (or :kbd:`Ctrl-Break` on Windows) to exit the server.

The above code renders as follows.

Press Ctrl-C (or Ctrl-Break on Windows) to exit the server.

Grammar, spelling, and capitalization

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

Preferred Avoid
add-on addon
ASCII ascii
and so on etc.
for example e.g.
GitHub Github, github
in other words i.e.
JavaScript Javascript, javascript, js
JSON json
nginx Nginx
plug-in plugin
Pyramid pyramid
Python python
reST or reStructuredText rst, restructuredtext
select check, tick (checkbox)
Setuptools setuptools
such as like
Unicode unicode
Unix UNIX, unix
URL url
verify be sure

Sphinx extensions

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.

sphinx.ext.autodoc

API documentation uses the Sphinx extension 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 documentation. Live examples can be found in Pyramid's API Documentation.

sphinx.ext.doctest

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. The following is an example.

.. testsetup:: group1

    a = 1
    b = 2

.. doctest:: group1

    >>> a + b
    3

And the rendered result.

>>> a + b
3

When we run doctests, the output would be similar to the following.

tox -e doctest

# ...

Document: index
---------------
1 items passed all tests:
   1 tests in group1
1 tests in 1 items.
1 passed and 0 failed.
Test passed.

Doctest summary
===============
    1 test
    0 failures in tests
    0 failures in setup code
    0 failures in cleanup code
build succeeded.

Testing of doctests in the sources finished, look at the results in ../.tox/doctest/doctest/output.txt.

sphinx.ext.intersphinx

sphinx.ext.intersphinx generates links to the documentation of objects in other projects.

sphinx.ext.todo

sphinx.ext.todo adds support for todo items.

sphinx.ext.viewcode

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. Live examples can be found in Pyramid's API Documentation.

repoze.sphinx.autointerface

repoze.sphinx.autointerface auto-generates API docs from Zope interfaces.

Script documentation

We currently use sphinxcontrib-autoprogram to generate program output of Pyramid's p* Scripts Documentation.