docs/notes/styleguide.rst

   1 .. _guide-style-guide:
   2
   3 =====================
   4 The Guide Style Guide
   5 =====================
   6
   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
  10 appropriate.
  11
  12 The Guide is written as :ref:`restructuredtext-ref`.
  13
  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
  16
  17 .. note:: On any page of the rendered HTML you can click "Show Source" to
  18    see how authors have styled the page.
  19
  20 Relevancy
  21 ---------
  22
  23 Strive to keep any contributions relevant to the :ref:`purpose of The Guide
  24 <about-ref>`.
  25
  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 conjunction
  33   with Python (ex: Git, Github, Databases), reference by linking to useful
  34   resources and describe why it's useful to Python.
  35 * When in doubt, ask.
  36
  37 Headings
  38 --------
  39
  40 Use the following styles for headings.
  41
  42 Chapter title::
  43
  44     #########
  45     Chapter 1
  46     #########
  47
  48 Page title::
  49
  50     ===================
  51     Time is an Illusion
  52     ===================
  53
  54 Section headings::
  55
  56     Lunchtime Doubly So
  57     -------------------
  58
  59 Sub section headings::
  60
  61     Very Deep
  62     ~~~~~~~~~
  63
  64 Prose
  65 -----
  66
  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
  69 to read.
  70
  71
  72 Code Examples
  73 -------------
  74
  75 Wrap all code examples at 70 characters to avoid horizontal scrollbars.
  76
  77 Command line examples::
  78
  79     .. code-block:: console
  80
  81         $ run command --help
  82         $ ls ..
  83
  84 Be sure to include the ``$`` prefix before each line.
  85
  86 Python interpreter examples::
  87
  88     Label the example::
  89
  90     .. code-block:: python
  91
  92         >>> import this
  93
  94 Python examples::
  95
  96     Descriptive title::
  97
  98     .. code-block:: python
  99
 100         def get_answer():
 101             return 42
 102
 103 Externally Linking
 104 ------------------
 105
 106 * Prefer labels for well known subjects (ex: proper nouns) when linking::
 107
 108     Sphinx_ is used to document Python.
 109
 110     .. _Sphinx: http://sphinx.pocoo.org
 111
 112 * Prefer to use descriptive labels with inline links instead of leaving bare
 113   links::
 114
 115     Read the `Sphinx Tutorial <http://sphinx.pocoo.org/tutorial.html>`_
 116
 117 * Avoid using labels such as "click here", "this", etc. preferring
 118   descriptive labels (SEO worthy) instead.
 119
 120 Linking to Sections in The Guide
 121 --------------------------------
 122
 123 To cross-reference other parts of this documentation, use the `:ref:
 124 <http://sphinx.pocoo.org/markup/inline.html#cross-referencing-arbitrary-locations>`_
 125 keyword and labels.
 126
 127 To make reference labels more clear and unique, always add a ``-ref`` suffix::
 128
 129     .. _some-section-ref:
 130
 131     Some Section
 132     ------------
 133
 134 Notes and Warnings
 135 ------------------
 136
 137 Make use of the appropriate `admonitions directives
 138 <http://sphinx.pocoo.org/rest.html#directives>`_ when making notes.
 139
 140 Notes::
 141
 142     .. note::
 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.
 146
 147 Warnings::
 148
 149     .. warning:: DON'T PANIC
 150
 151 TODOs
 152 -----
 153
 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.
 158
 159 ::
 160
 161     .. todo::
 162         Learn the Ultimate Answer to the Ultimate Question
 163         of Life, The Universe, and Everything
 164