:orphan:

=========================
Documentation Conventions
=========================

This document describes the conventions used in pip's documentation. We
expect it to evolve over time as additional conventions are identified
and past conventions are rendered obsolete.

.. note::

    Currently, these conventions are not enforced automatically, and
    need to be verified manually during code review. We are interested
    in linters that can help us enforce these conventions automatically.


Files
=====

Naming
------

Folder names should be a single word, all lowercase.

File names must use the kebab-case style (all lowercase, hyphen for
separating words) and have the extension ``.rst``.

Encoding
--------

All files in our documentation must use UTF-8 encoding.


File Layout
===========

Line Length
-----------

Limit all lines to a maximum of 72 characters, where possible. This may
be exceeded when it does not make sense to abide by it (eg. long links,
code blocks).

Indentation
-----------

We use 4 spaces for indentation.

::

    .. note::

        Directive blocks

    ::

        Code block.

Bullet lists are the only exception to the 4 spaces rule, using 2 spaces
when wrapping lines.

::

    - This is a bullet list.
    - This is a lot of text in a single bullet which would require wrapping
      across multiple lines to fit in the line length limits.


Headings
========

Use the following symbols to create headings:

#. ``=`` with overline
#. ``=``
#. ``-``
#. ``^``
#. ``'``
#. ``*``

For visual separation from the rest of the content, all other headings
must have one empty line before and after. Heading 2 (``=``) should have
two empty lines before, for indicating the end of the section prior to
it.

::

    =========
    Heading 1
    =========

    Lorem ipsum dolor sit amet consectetur adipisicing elit.


    Heading 2
    =========

    Lorem ipsum dolor sit amet consectetur adipisicing elit.

    Heading 3
    ---------

    Lorem ipsum dolor sit amet consectetur adipisicing elit.

    Heading 4
    ^^^^^^^^^

    Lorem ipsum dolor sit amet consectetur adipisicing elit.

    Heading 5
    '''''''''

    Lorem ipsum dolor sit amet consectetur adipisicing elit.

    Heading 6
    *********

    Lorem ipsum dolor sit amet consectetur adipisicing elit.


Writing
=======

pip is a proper noun, and spelt all lowercase. Do not capitalize pip as
"Pip" at the start of a sentence.

Avoid using phrases such as "easy", "just", "simply" etc, which imply
that the task is trivial. If it were trivial, the user wouldn't be
reading the documentation for it.
