notes/license

.. _about-ref:

Style Guide

For all contributions, please follow the :ref:`guide-style-guide`.

.. _todo-list-ref:

.. _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::

Page title::

Section headings::

Sub section headings::

Code Examples

Wrap all code examples within 70 characters to avoid horizontal scrollbars.

Command line examples::

Be sure to include the ``$`` prefix before each line.

Python interpreter examples::

Python examples::

Externally Linking

* Prefer labels for well known subjects (ex: proper nouns) when linking::

* Prefer to use descriptive labels with inline links instead of leaving bare links::

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

Notes and Warnings

Make use of the appropriate `admonitions directives <http://sphinx.pocoo.org/rest.html#directives>`_ when making notes.

Notes::

Warnings::

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.

::

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