You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/notes/styleguide.rst
+58-26Lines changed: 58 additions & 26 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,23 +4,34 @@
4
4
The Guide Style Guide
5
5
=====================
6
6
7
-
As with all documentation, having a consistent formating helps make the document more understandable. In order to make The Guide easier to digest, all contributions should fit within the rules of this style guide where approriate.
7
+
As with all documentation, having a consistent formating helps make the
8
+
document more understandable. In order to make The Guide easier to digest,
9
+
all contributions should fit within the rules of this style guide where
10
+
approriate.
8
11
9
-
The Guide is written as :ref:`restructuredtext-ref`.
12
+
The Guide is written as :ref:`restructuredtext-ref`.
10
13
11
-
.. note:: Parts of The Guide may not yet match this style guide. Feel free to update those parts to by in sync with The Guide Style Guide
14
+
.. note:: Parts of The Guide may not yet match this style guide. Feel free
15
+
to update those parts to by in sync with The Guide Style Guide
12
16
13
-
.. note:: On any page of the rendered HTML you can click "Show Source" to see how authors have styled the page.
17
+
.. note:: On any page of the rendered HTML you can click "Show Source" to
18
+
see how authors have styled the page.
14
19
15
20
Relevancy
16
21
---------
17
22
18
-
Stride to keep any contributions relevant to the :ref:`purpose of The Guide <about-ref>`.
19
-
20
-
* Avoid including too much information on subjects that don't directly relate to Python development.
21
-
* Prefer to link to other sources if the information is already out there. Be sure to describe what and why you are linking.
22
-
* `Cite <http://sphinx.pocoo.org/rest.html?highlight=citations#citations>`_ references where needed.
23
-
* If a subject isn't directly relevant to Python, but useful in conjuction with Python (ex: Git, Github, Databases), reference by linking to useful resouces and describe why it's useful to Python.
23
+
Stride to keep any contributions relevant to the :ref:`purpose of The Guide
24
+
<about-ref>`.
25
+
26
+
* Avoid including too much information on subjects that don't directly
27
+
relate to Python development.
28
+
* Prefer to link to other sources if the information is already out there.
* If a subject isn't directly relevant to Python, but useful in conjuction
33
+
with Python (ex: Git, Github, Databases), reference by linking to useful
34
+
resouces and describe why it's useful to Python.
24
35
* When in doubt, ask.
25
36
26
37
Headings
@@ -49,11 +60,19 @@ Sub section headings::
49
60
50
61
Very Deep
51
62
~~~~~~~~~
52
-
63
+
64
+
Prose
65
+
-----
66
+
67
+
Wrap text lines at 78 characters. Where necessary, lines may exceed 78
68
+
characters, especially if wrapping would make the source text more difficult
69
+
to read.
70
+
71
+
53
72
Code Examples
54
73
-------------
55
74
56
-
Wrap all code examples within 70 characters to avoid horizontal scrollbars.
75
+
Wrap all code examples at 70 characters to avoid horizontal scrollbars.
57
76
58
77
Command line examples::
59
78
@@ -65,17 +84,21 @@ Command line examples::
65
84
Be sure to include the ``$`` prefix before each line.
66
85
67
86
Python interpreter examples::
68
-
87
+
69
88
Label the example::
70
-
89
+
90
+
.. code-block:: python
91
+
71
92
>>> import this
72
93
73
94
Python examples::
74
95
75
96
Descriptive title::
76
97
98
+
.. code-block:: python
99
+
77
100
def get_answer():
78
-
return 42
101
+
return 42
79
102
80
103
Externally Linking
81
104
------------------
@@ -86,16 +109,20 @@ Externally Linking
86
109
87
110
.. _Sphinx: http://sphinx.pocoo.org
88
111
89
-
* Prefer to use descriptive labels with inline links instead of leaving bare links::
112
+
* Prefer to use descriptive labels with inline links instead of leaving bare
113
+
links::
90
114
91
115
Read the `Sphinx Tutorial <http://sphinx.pocoo.org/tutorial.html>`_
92
116
93
-
* Avoid using labels such as "click here", "this", etc. preferring decriptive labels (SEO worthy) instead.
117
+
* Avoid using labels such as "click here", "this", etc. preferring
118
+
decriptive labels (SEO worthy) instead.
94
119
95
120
Linking to Sections in The Guide
96
121
--------------------------------
97
122
98
-
To cross-reference other parts of this documentation, use the `:ref: <http://sphinx.pocoo.org/markup/inline.html#cross-referencing-arbitrary-locations>`_ keyword and labels.
123
+
To cross-reference other parts of this documentation, use the `:ref:
To make reference labels more clear and unique, always add a ``-ref`` suffix::
101
128
@@ -107,26 +134,31 @@ To make reference labels more clear and unique, always add a ``-ref`` suffix::
107
134
Notes and Warnings
108
135
------------------
109
136
110
-
Make use of the appropriate `admonitions directives <http://sphinx.pocoo.org/rest.html#directives>`_ when making notes.
137
+
Make use of the appropriate `admonitions directives
138
+
<http://sphinx.pocoo.org/rest.html#directives>`_ when making notes.
111
139
112
140
Notes::
113
-
114
-
.. note::
141
+
142
+
.. note::
115
143
The Hitchhiker’s Guide to the Galaxy has a few things to say
116
144
on the subject of towels. A towel, it says, is about the most
117
145
massively useful thing an interstellar hitch hiker can have.
118
146
119
147
Warnings::
120
-
148
+
121
149
.. warning:: DON'T PANIC
122
150
123
151
TODOs
124
152
-----
125
153
126
-
Please mark any incomplete areas of The Guide with a `todo directive <http://sphinx.pocoo.org/ext/todo.html?highlight=todo#directive-todo>`_. To avoid cluttering the :ref:`todo-list-ref`, use a single ``todo`` for stub documents or large incomplete sections.
154
+
Please mark any incomplete areas of The Guide with a `todo directive
155
+
<http://sphinx.pocoo.org/ext/todo.html?highlight=todo#directive-todo>`_. To
156
+
avoid cluttering the :ref:`todo-list-ref`, use a single ``todo`` for stub
157
+
documents or large incomplete sections.
127
158
128
159
::
129
160
130
-
.. todo::
131
-
Learn the Ultimate Answer to the Ultimate Question
132
-
of Life, The Universe, and Everything
161
+
.. todo::
162
+
Learn the Ultimate Answer to the Ultimate Question
0 commit comments