The Guide Style Guide

    The Guide is written as reStructuredText.

    Note

    Parts of The Guide may not yet match this style guide. Feel freeto update those parts to be in sync with The Guide Style Guide

    Note

    On any page of the rendered HTML you can click “Show Source” tosee how authors have styled the page.

    Strive to keep any contributions relevant to the .

    • Avoid including too much information on subjects that don’t directlyrelate to Python development.
    • Prefer to link to other sources if the information is already out there.Be sure to describe what and why you are linking.
    • Citereferences where needed.
    • If a subject isn’t directly relevant to Python, but useful in conjunctionwith Python (e.g., Git, GitHub, Databases), reference by linking to usefulresources, and describe why it’s useful to Python.
    • When in doubt, ask.

    Headings

    Use the following styles for headings.

    Chapter title:

    1. *******************
    2. *******************

    Section headings:

    1. Lunchtime Doubly So
    2. ===================

    Sub section headings:

    1. Very Deep
    2. ---------

    Wrap text lines at 78 characters. Where necessary, lines may exceed 78characters, especially if wrapping would make the source text more difficultto read.

    Use Standard American English, not British English.

    Use of the serial comma(also known as the Oxford comma) is 100% non-optional. Any attempt tosubmit content with a missing serial comma will result in permanent banishmentfrom this project, due to complete and total lack of taste.

    Banishment? Is this a joke? Hopefully we will never have to find out.

    Code Examples

    Wrap all code examples at 70 characters to avoid horizontal scrollbars.

    Command line examples:

    Python interpreter examples:

    1. Label the example::
    2.  
    3. .. code-block:: python
    4.  
    5.     >>> import this

    Python examples:

    1. Descriptive title::
    2.  
    3. .. code-block:: python
    4.  
    5.         return 42
    • Prefer labels for well known subjects (e.g. proper nouns) when linking:
    1. Sphinx_ is used to document Python.
    2.  
    3. .. _Sphinx: http://sphinx.pocoo.org
    • Prefer to use descriptive labels with inline links instead of leaving barelinks:
    • Avoid using labels such as “click here”, “this”, etc., preferringdescriptive labels (SEO worthy) instead.

    Linking to Sections in The Guide

    To cross-reference other parts of this documentation, use the keyword and labels.

    To make reference labels more clear and unique, always add a suffix:

    1. .. _some-section-ref:
    2.  
    3. Some Section
    4. ------------

    Make use of the appropriate admonitions directives when making notes.

    Notes:

    1. .. note::
    2.     The Hitchhiker’s Guide to the Galaxy has a few things to say
    3.     on the subject of towels. A towel, it says, is about the most

    Warnings:

    1. .. warning:: DON'T PANIC

    TODOs

    Please mark any incomplete areas of The Guide with a todo directive. Toavoid cluttering the , use a single for stubdocuments or large incomplete sections.