The Guide Style Guide¶
As with all documentation, having a consistent format 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 appropriate.
The Guide is written as reStructuredText.
Parts of The Guide may not yet match this style guide. Feel free to update those parts to be in sync with The Guide Style Guide
On any page of the rendered HTML you can click “Show Source” to see how authors have styled the page.
Strive to keep any contributions relevant to the purpose of The Guide.
- 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 references where needed.
- If a subject isn’t directly relevant to Python, but useful in conjunction with Python (e.g., Git, GitHub, Databases), reference by linking to useful resources, and describe why it’s useful to Python.
- When in doubt, ask.
Use the following styles for headings.
######### Chapter 1 #########
=================== Time is an Illusion ===================
Lunchtime Doubly So -------------------
Sub section headings:
Very Deep ~~~~~~~~~
Wrap text lines at 78 characters. Where necessary, lines may exceed 78 characters, especially if wrapping would make the source text more difficult to read.
Use of the serial comma (also known as the Oxford comma) is 100% non-optional. Any attempt to submit content with a missing serial comma will result in permanent banishment from this project, due to complete and total lack of taste.
Banishment? Is this a joke? Hopefully we will never have to find out.
Wrap all code examples at 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:: .. code-block:: python >>> import this
Descriptive title:: .. code-block:: python def get_answer(): return 42
Notes and Warnings¶
Make use of the appropriate admonitions directives when making 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.
.. warning:: DON'T PANIC