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
+45-25Lines changed: 45 additions & 25 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,7 +60,7 @@ Sub section headings::
49
60
50
61
Very Deep
51
62
~~~~~~~~~
52
-
63
+
53
64
Code Examples
54
65
-------------
55
66
@@ -65,17 +76,17 @@ Command line examples::
65
76
Be sure to include the ``$`` prefix before each line.
66
77
67
78
Python interpreter examples::
68
-
79
+
69
80
Label the example::
70
-
81
+
71
82
>>> import this
72
83
73
84
Python examples::
74
85
75
86
Descriptive title::
76
87
77
88
def get_answer():
78
-
return 42
89
+
return 42
79
90
80
91
Externally Linking
81
92
------------------
@@ -86,16 +97,20 @@ Externally Linking
86
97
87
98
.. _Sphinx: http://sphinx.pocoo.org
88
99
89
-
* Prefer to use descriptive labels with inline links instead of leaving bare links::
100
+
* Prefer to use descriptive labels with inline links instead of leaving bare
101
+
links::
90
102
91
103
Read the `Sphinx Tutorial <http://sphinx.pocoo.org/tutorial.html>`_
92
104
93
-
* Avoid using labels such as "click here", "this", etc. preferring decriptive labels (SEO worthy) instead.
105
+
* Avoid using labels such as "click here", "this", etc. preferring
106
+
decriptive labels (SEO worthy) instead.
94
107
95
108
Linking to Sections in The Guide
96
109
--------------------------------
97
110
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.
111
+
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
116
@@ -107,26 +122,31 @@ To make reference labels more clear and unique, always add a ``-ref`` suffix::
107
122
Notes and Warnings
108
123
------------------
109
124
110
-
Make use of the appropriate `admonitions directives <http://sphinx.pocoo.org/rest.html#directives>`_ when making notes.
125
+
Make use of the appropriate `admonitions directives
126
+
<http://sphinx.pocoo.org/rest.html#directives>`_ when making notes.
111
127
112
128
Notes::
113
-
114
-
.. note::
129
+
130
+
.. note::
115
131
The Hitchhiker’s Guide to the Galaxy has a few things to say
116
132
on the subject of towels. A towel, it says, is about the most
117
133
massively useful thing an interstellar hitch hiker can have.
118
134
119
135
Warnings::
120
-
136
+
121
137
.. warning:: DON'T PANIC
122
138
123
139
TODOs
124
140
-----
125
141
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.
142
+
Please mark any incomplete areas of The Guide with a `todo directive
143
+
<http://sphinx.pocoo.org/ext/todo.html?highlight=todo#directive-todo>`_. To
144
+
avoid cluttering the :ref:`todo-list-ref`, use a single ``todo`` for stub
145
+
documents or large incomplete sections.
127
146
128
147
::
129
148
130
-
.. todo::
131
-
Learn the Ultimate Answer to the Ultimate Question
132
-
of Life, The Universe, and Everything
149
+
.. todo::
150
+
Learn the Ultimate Answer to the Ultimate Question
0 commit comments