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
12 The Guide is written as :ref:`restructuredtext-ref`.
14 .. note:: Parts of The Guide may not yet match this style guide. Feel free
15 to update those parts to be in sync with The Guide Style Guide
17 .. note:: On any page of the rendered HTML you can click "Show Source" to
18 see how authors have styled the page.
23 Strive to keep any contributions relevant to the :ref:`purpose of The Guide
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.
40 Use the following styles for headings.
59 Sub section headings::
67 Wrap text lines at 78 characters. Where necessary, lines may exceed 78
68 characters, especially if wrapping would make the source text more difficult
75 Wrap all code examples at 70 characters to avoid horizontal scrollbars.
77 Command line examples::
79 .. code-block:: console
84 Be sure to include the ``$`` prefix before each line.
86 Python interpreter examples::
90 .. code-block:: python
98 .. code-block:: python
106 * Prefer labels for well known subjects (ex: proper nouns) when linking::
108 Sphinx_ is used to document Python.
110 .. _Sphinx: http://sphinx.pocoo.org
112 * Prefer to use descriptive labels with inline links instead of leaving bare
115 Read the `Sphinx Tutorial <http://sphinx.pocoo.org/tutorial.html>`_
117 * Avoid using labels such as "click here", "this", etc. preferring
118 decriptive labels (SEO worthy) instead.
120 Linking to Sections in The Guide
121 --------------------------------
123 To cross-reference other parts of this documentation, use the `:ref:
124 <http://sphinx.pocoo.org/markup/inline.html#cross-referencing-arbitrary-locations>`_
127 To make reference labels more clear and unique, always add a ``-ref`` suffix::
129 .. _some-section-ref:
137 Make use of the appropriate `admonitions directives
138 <http://sphinx.pocoo.org/rest.html#directives>`_ when making notes.
143 The Hitchhiker’s Guide to the Galaxy has a few things to say
144 on the subject of towels. A towel, it says, is about the most
145 massively useful thing an interstellar hitch hiker can have.
149 .. warning:: DON'T PANIC
154 Please mark any incomplete areas of The Guide with a `todo directive
155 <http://sphinx.pocoo.org/ext/todo.html?highlight=todo#directive-todo>`_. To
156 avoid cluttering the :ref:`todo-list-ref`, use a single ``todo`` for stub
157 documents or large incomplete sections.
162 Learn the Ultimate Answer to the Ultimate Question
163 of Life, The Universe, and Everything