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
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
|
.. _docs-style:
==================================
Writing Documentation for Flake8
==================================
The maintainers of |Flake8| believe strongly in benefit of style guides.
Hence, for all contributors who wish to work on our documentation, we've
put together a loose set of guidelines and best practices when adding to
our documentation.
View the docs locally before submitting
=======================================
You can and should generate the docs locally before you submit a pull request
with your changes. You can build the docs by running:
.. prompt:: bash
tox -e docs
From the directory containing the ``tox.ini`` file (which also contains the
``docs/`` directory that this file lives in).
.. note::
If the docs don't build locally, they will not build in our continuous
integration system. We will generally not merge any pull request that
fails continuous integration.
Run the docs linter tests before submitting
===========================================
You should run the ``doc8`` linter job before you're ready to commit and fix
any errors found.
Capitalize Flake8 in prose
==========================
We believe that by capitalizing |Flake8| in prose, we can help reduce
confusion between the command-line usage of ``flake8`` and the project.
We also have defined a global replacement ``|Flake8|`` that should be used
and will replace each instance with ``:program:`Flake8```.
Use the prompt directive for command-line examples
==================================================
When documenting something on the command-line, use the ``.. prompt::``
directive to make it easier for users to copy and paste into their terminal.
Example:
.. code-block:: restructuredtext
.. prompt:: bash
flake8 --select E123,W503 dir/
flake8 --ignore E24,W504 dir
Wrap lines around 79 characters
===============================
We use a maximum line-length in our documentation that is similar to the
default in |Flake8|. Please wrap lines at 79 characters (or less).
Use two new-lines before new sections
=====================================
After the final paragraph of a section and before the next section title,
use two new-lines to separate them. This makes reading the plain-text
document a little nicer. Sphinx ignores these when rendering so they have
no semantic meaning.
Example:
.. code-block:: restructuredtext
Section Header
==============
Paragraph.
Next Section Header
===================
Paragraph.
Surround document titles with equal symbols
===========================================
To indicate the title of a document, we place an equal number of ``=`` symbols
on the lines before and after the title. For example:
.. code-block:: restructuredtext
==================================
Writing Documentation for Flake8
==================================
Note also that we "center" the title by adding a leading space and having
extra ``=`` symbols at the end of those lines.
Use the option template for new options
=======================================
All of |Flake8|'s command-line options are documented in the User Guide. Each
option is documented individually using the ``.. option::`` directive provided
by Sphinx. At the top of the document, in a reStructuredText comment, is a
template that should be copied and pasted into place when documening new
options.
.. note::
The ordering of the options page is the order that options are printed
in the output of:
.. prompt:: bash
flake8 --help
Please insert your option documentation according to that order.
Use anchors for easy reference linking
======================================
Use link anchors to allow for other areas of the documentation to use the
``:ref:`` role for intralinking documentation. Example:
.. code-block:: restructuredtext
.. _use-anchors:
Use anchors for easy reference linking
======================================
.. code-block:: restructuredtext
Somewhere in this paragraph we will :ref:`reference anchors
<use-anchors>`.
.. note::
You do not need to provide custom text for the ``:ref:`` if the title of
the section has a title that is sufficient.
Keep your audience in mind
==========================
|Flake8|'s documentation has three distinct (but not separate) audiences:
#. Users
#. Plugin Developers
#. Flake8 Developers and Contributors
At the moment, you're one of the third group (because you're contributing
or thinking of contributing).
Consider that most Users aren't very interested in the internal working of
|Flake8|. When writing for Users, focus on how to do something or the
behaviour of a certain piece of configuration or invocation.
Plugin developers will only care about the internals of |Flake8| as much as
they will have to interact with that. Keep discussions of internal to the
mininmum required.
Finally, Flake8 Developers and Contributors need to know how everything fits
together. We don't need detail about every line of code, but cogent
explanations and design specifications will help future developers understand
the Hows and Whys of |Flake8|'s internal design.
|
