1:orphan:
2
3=========================
4Documentation Conventions
5=========================
6
7This document describes the conventions used in pip's documentation. We
8expect it to evolve over time as additional conventions are identified
9and past conventions are rendered obsolete.
10
11.. note::
12
13   Currently, these conventions are not enforced automatically, and
14   need to be verified manually during code review. We are interested
15   in linters that can help us enforce these conventions automatically.
16
17
18Files
19=====
20
21Naming
22------
23
24Folder names should be a single word, all lowercase.
25
26File names must use the kebab-case style (all lowercase, hyphen for
27separating words) and have the extension ``.rst``.
28
29Encoding
30--------
31
32All files in our documentation must use UTF-8 encoding.
33
34Line Length
35-----------
36
37Limit all lines to a maximum of 72 characters, where possible. This may
38be exceeded when it does not make sense to abide by it (eg. long links,
39code blocks).
40
41Headings
42========
43
44Use the following symbols to create headings:
45
46#. ``=`` with overline
47#. ``=``
48#. ``-``
49#. ``^``
50#. ``'``
51#. ``*``
52
53For visual separation from the rest of the content, all other headings
54must have one empty line before and after. Heading 2 (``=``) should have
55two empty lines before, for indicating the end of the section prior to
56it.
57
58::
59
60   =========
61   Heading 1
62   =========
63
64   Lorem ipsum dolor sit amet consectetur adipisicing elit.
65
66
67   Heading 2
68   =========
69
70   Lorem ipsum dolor sit amet consectetur adipisicing elit.
71
72   Heading 3
73   ---------
74
75   Lorem ipsum dolor sit amet consectetur adipisicing elit.
76
77   Heading 4
78   ^^^^^^^^^
79
80   Lorem ipsum dolor sit amet consectetur adipisicing elit.
81
82   Heading 5
83   '''''''''
84
85   Lorem ipsum dolor sit amet consectetur adipisicing elit.
86
87   Heading 6
88   *********
89
90   Lorem ipsum dolor sit amet consectetur adipisicing elit.
91
92
93Writing
94=======
95
96.. note::
97
98   We're still discussing *how* pip should be capitalized in prose. The
99   current statement here is tentative.
100
101pip is a proper noun, and spelt all lowercase. Do not capitalize pip as
102"Pip" at the start of a sentence.
103
104Avoid using phrases such as "easy", "just", "simply" etc, which imply
105that the task is trivial. If it were trivial, the user wouldn't be
106reading the documentation for it.
107