kennethreitz/python-guide
1
0
Fork 0
mirror of https://github.com/kennethreitz/python-guide.git synced 2026-06-05 14:50:19 +00:00
Code Issues Packages Projects Releases Wiki Activity

wrap to 78chars, cleanup some trailing whitespace

Browse Source
This commit is contained in:
Dan Crosta
2011-12-30 19:47:18 -05:00
parent 4c68f91c8a
commit b9d9a1a22a
1 changed files with 44 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/notes/styleguide.rst
+44 -24
View File
@@ -4,23 +4,34 @@
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>`.
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.
* 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
@@ -49,7 +60,7 @@ Sub section headings::
Very Deep
~~~~~~~~~
Code Examples
-------------
@@ -65,9 +76,9 @@ Command line examples::
Be sure to include the ``$`` prefix before each line.
Python interpreter examples::
Label the example::
>>> import this
Python examples::
@@ -75,7 +86,7 @@ Python examples::
Descriptive title::
def get_answer():
return 42
return 42
Externally Linking
------------------
@@ -86,16 +97,20 @@ 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::
@@ -107,26 +122,31 @@ 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
.. todo::
Learn the Ultimate Answer to the Ultimate Question
of Life, The Universe, and Everything