The Guide Style Guide
=====================
-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.
+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.
-The Guide is written as :ref:`restructuredtext-ref`.
+The Guide is written as :ref:`restructuredtext-ref`.
-.. 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
+.. 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
-.. note:: On any page of the rendered HTML you can click "Show Source" to see how authors have styled the page.
+.. note:: On any page of the rendered HTML you can click "Show Source" to
+ see how authors have styled the page.
Relevancy
---------
-Stride to keep any contributions relevant to the :ref:`purpose of The Guide <about-ref>`.
-
-* Avoid including too much information on subjects that don't directly relate to Python development.
-* Prefer to link to other sources if the information is already out there. Be sure to describe what and why you are linking.
-* `Cite <http://sphinx.pocoo.org/rest.html?highlight=citations#citations>`_ references where needed.
-* 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.
+Stride to keep any contributions relevant to the :ref:`purpose of The Guide
+<about-ref>`.
+
+* Avoid including too much information on subjects that don't directly
+ relate to Python development.
+* Prefer to link to other sources if the information is already out there.
+ Be sure to describe what and why you are linking.
+* `Cite <http://sphinx.pocoo.org/rest.html?highlight=citations#citations>`_
+ references where needed.
+* 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.
* When in doubt, ask.
Headings
Very Deep
~~~~~~~~~
-
+
Code Examples
-------------
Be sure to include the ``$`` prefix before each line.
Python interpreter examples::
-
+
Label the example::
-
+
>>> import this
Python examples::
Descriptive title::
def get_answer():
- return 42
+ return 42
Externally Linking
------------------
.. _Sphinx: http://sphinx.pocoo.org
-* Prefer to use descriptive labels with inline links instead of leaving bare links::
+* Prefer to use descriptive labels with inline links instead of leaving bare
+ links::
Read the `Sphinx Tutorial <http://sphinx.pocoo.org/tutorial.html>`_
-* Avoid using labels such as "click here", "this", etc. preferring decriptive labels (SEO worthy) instead.
+* Avoid using labels such as "click here", "this", etc. preferring
+ decriptive labels (SEO worthy) instead.
Linking to Sections in The Guide
--------------------------------
-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.
+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.
To make reference labels more clear and unique, always add a ``-ref`` suffix::
Notes and Warnings
------------------
-Make use of the appropriate `admonitions directives <http://sphinx.pocoo.org/rest.html#directives>`_ when making notes.
+Make use of the appropriate `admonitions directives
+<http://sphinx.pocoo.org/rest.html#directives>`_ when making notes.
Notes::
-
- .. note::
+
+ .. note::
The Hitchhiker’s Guide to the Galaxy has a few things to say
on the subject of towels. A towel, it says, is about the most
massively useful thing an interstellar hitch hiker can have.
Warnings::
-
+
.. warning:: DON'T PANIC
TODOs
-----
-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.
+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.
::
- .. todo::
- Learn the Ultimate Answer to the Ultimate Question
- of Life, The Universe, and Everything
\ No newline at end of file
+ .. todo::
+ Learn the Ultimate Answer to the Ultimate Question
+ of Life, The Universe, and Everything
+