Skip to content

Commit b9d9a1a

Browse files
committed
wrap to 78chars, cleanup some trailing whitespace
1 parent 4c68f91 commit b9d9a1a

File tree

1 file changed

+45
-25
lines changed

1 file changed

+45
-25
lines changed

docs/notes/styleguide.rst

Lines changed: 45 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -4,23 +4,34 @@
44
The Guide Style Guide
55
=====================
66

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.
811

9-
The Guide is written as :ref:`restructuredtext-ref`.
12+
The Guide is written as :ref:`restructuredtext-ref`.
1013

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
1216

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.
1419

1520
Relevancy
1621
---------
1722

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.
29+
Be sure to describe what and why you are linking.
30+
* `Cite <http://sphinx.pocoo.org/rest.html?highlight=citations#citations>`_
31+
references where needed.
32+
* 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.
2435
* When in doubt, ask.
2536

2637
Headings
@@ -49,7 +60,7 @@ Sub section headings::
4960

5061
Very Deep
5162
~~~~~~~~~
52-
63+
5364
Code Examples
5465
-------------
5566

@@ -65,17 +76,17 @@ Command line examples::
6576
Be sure to include the ``$`` prefix before each line.
6677

6778
Python interpreter examples::
68-
79+
6980
Label the example::
70-
81+
7182
>>> import this
7283

7384
Python examples::
7485

7586
Descriptive title::
7687

7788
def get_answer():
78-
return 42
89+
return 42
7990

8091
Externally Linking
8192
------------------
@@ -86,16 +97,20 @@ Externally Linking
8697

8798
.. _Sphinx: http://sphinx.pocoo.org
8899

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::
90102

91103
Read the `Sphinx Tutorial <http://sphinx.pocoo.org/tutorial.html>`_
92104

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.
94107

95108
Linking to Sections in The Guide
96109
--------------------------------
97110

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:
112+
<http://sphinx.pocoo.org/markup/inline.html#cross-referencing-arbitrary-locations>`_
113+
keyword and labels.
99114

100115
To make reference labels more clear and unique, always add a ``-ref`` suffix::
101116

@@ -107,26 +122,31 @@ To make reference labels more clear and unique, always add a ``-ref`` suffix::
107122
Notes and Warnings
108123
------------------
109124

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.
111127

112128
Notes::
113-
114-
.. note::
129+
130+
.. note::
115131
The Hitchhiker’s Guide to the Galaxy has a few things to say
116132
on the subject of towels. A towel, it says, is about the most
117133
massively useful thing an interstellar hitch hiker can have.
118134

119135
Warnings::
120-
136+
121137
.. warning:: DON'T PANIC
122138

123139
TODOs
124140
-----
125141

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.
127146

128147
::
129148

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
151+
of Life, The Universe, and Everything
152+

0 commit comments

Comments
 (0)