1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
|
: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.
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).
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
=======
.. note::
We're still discussing *how* pip should be capitalized in prose. The
current statement here is tentative.
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.
|
