First pass at styleguide

Author: six8

TODO.rst

@@ -1,4 +1,3 @@
 * Establish "use this" vs "alternatives are...." recommendations
-* Style Guide (for Guide)
 
 .. todolist::

docs/contents.rst.inc

@@ -84,4 +84,4 @@ Contibution notes and legal information are here (for those interested).
    :maxdepth: 2
 
    notes/contribute
-   notes/license
+   notes/license   

docs/intro/duction.rst

@@ -3,6 +3,8 @@ Introduction
 
 .. todo:: write a general blurb introducing the Python language
 
+.. _about-ref:
+
 About This Guide
 ----------------
 

docs/notes/contribute.rst

@@ -8,6 +8,12 @@ issue on GitHub_. To submit patches, please send a pull request on GitHub_.
 Once your changes get merged back in, you'll automatically be added to the
 `Contributors List <https://github.com/kennethreitz/python-guide/contributors>`_.
 
+Style Guide
+-----------
+
+For all contributions, please follow the :ref:`guide-style-guide`.
+
+.. _todo-list-ref:
 
 Todo List
 ---------

docs/notes/styleguide.rst

@@ -0,0 +1,132 @@
+.. _guide-style-guide:
+
+=====================
+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.
+
+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:: 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.
+* When in doubt, ask.
+
+Headings
+--------
+
+Use the following styles for headings.
+
+Chapter title::
+
+    #########
+    Chapter 1
+    #########
+
+Page title::
+
+    ===================
+    Time is an Illusion
+    ===================
+
+Section headings::
+
+    Lunchtime Doubly So
+    -------------------
+
+Sub section headings::
+
+    Very Deep
+    ~~~~~~~~~
+        
+Code Examples
+-------------
+
+Wrap all code examples within 70 characters to avoid horizontal scrollbars.
+
+Command line examples::
+
+    .. code-block:: console
+
+        $ run command --help
+        $ ls ..
+
+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    
+
+Externally Linking
+------------------
+
+* Prefer labels for well known subjects (ex: proper nouns) when linking::
+
+    Sphinx_ is used to document Python.
+
+    .. _Sphinx: http://sphinx.pocoo.org
+
+* 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.
+
+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 make reference labels more clear and unique, always add a ``-ref`` suffix::
+
+    .. _some-section-ref:
+
+    Some Section
+    ------------
+
+Notes and Warnings
+------------------
+
+Make use of the appropriate `admonitions directives <http://sphinx.pocoo.org/rest.html#directives>`_ when making notes.
+
+Notes::
+    
+    .. 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.
+
+::
+
+    .. todo:: 
+        Learn the Ultimate Answer to the Ultimate Question 
+        of Life, The Universe, and Everything

docs/writing/documentation.rst

@@ -59,9 +59,20 @@ Multi-line docstrings: ::
 
 Sphinx
 ------
-Sphinx (http://sphinx.pocoo.org) is a tool  which converts documentation in the reStructured text markup language into a range of output formats including HTML, LaTeX (for printable PDF versions), manual pages and plain text.
+Sphinx_ is a tool which converts documentation in the :ref:`restructuredtext-ref` markup language into a range of output formats including HTML, LaTeX (for printable PDF versions), manual pages and plain text.
 
+.. note:: This Guide is built with Sphinx_
 
+.. _Sphinx: http://sphinx.pocoo.org
+
+.. _restructuredtext-ref:
+
+reStructuredText
+----------------
+
+Most Python documentation is written with reStructuredText_. The `reStructuredText Primer <http://sphinx.pocoo.org/rest.html>`_ and the `reStructuredText Quick Reference <http://docutils.sourceforge.net/docs/user/rst/quickref.html>`_ should help you familiarize yourself with its syntax.
+
+.. _reStructuredText: http://docutils.sourceforge.net/rst.html
 
 Other Tools
 :::::::::::