diff --git a/docs/notes/styleguide.rst b/docs/notes/styleguide.rst index 619c6daff..7da4cd2b3 100644 --- a/docs/notes/styleguide.rst +++ b/docs/notes/styleguide.rst @@ -1,8 +1,8 @@ .. _guide-style-guide: -===================== +##################### The Guide Style Guide -===================== +##################### .. image:: /_static/photos/33573755856_7f43d43adf_k_d.jpg @@ -13,14 +13,18 @@ appropriate. 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 be in sync with The Guide Style Guide +.. note:: + 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. -.. note:: On any page of the rendered HTML you can click "Show Source" to - see how authors have styled the page. +.. note:: + On any page of the rendered HTML you can click "Show Source" to + see how authors have styled the page. + +********* Relevancy ---------- +********* Strive to keep any contributions relevant to the :ref:`purpose of The Guide `. @@ -36,8 +40,36 @@ Strive to keep any contributions relevant to the :ref:`purpose of The Guide resources, and describe why it's useful to Python. * When in doubt, ask. + +********** +Whitespace +********** + +Indentation +=========== + +4 spaces, no tabs. + +Blank lines +=========== + +* Two blank lines before *chapter title* and *page title*. +* One blank line before all other headings. +* One blank line after all headings. +* One blank line before and after a directive, *except for notes, no blank + lines after it*. + +.. code-block:: reStructuredText + + Text... + + .. note:: + My note. + + +******** Headings --------- +******** Use the following styles for headings. @@ -45,34 +77,42 @@ Chapter title: .. code-block:: rest - ######### - Chapter 1 - ######### + ############# + H1: Chapter 1 + ############# Page title: .. code-block:: rest - =================== - Time is an Illusion - =================== + *********************** + H2: Time is an Illusion + *********************** Section headings: .. code-block:: rest - Lunchtime Doubly So - ------------------- + H3: Lunchtime Doubly So + ======================= Sub section headings: .. code-block:: rest - Very Deep - ~~~~~~~~~ + H4: Very Deep + ------------- + +Further information on headings formatting can be found on `Style guide for Sphinx-based documentations`_ +or `Sphinx reStructuredText Primer`_. + +.. _Style guide for Sphinx-based documentations: https://documentation-style-guide-sphinx.readthedocs.io/en/latest/style-guide.html#headings +.. _Sphinx reStructuredText Primer: http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#sections + +***** Prose ------ +***** Wrap text lines at 78 characters. Where necessary, lines may exceed 78 characters, especially if wrapping would make the source text more difficult @@ -85,8 +125,10 @@ from this project, due to complete and total lack of taste. Banishment? Is this a joke? Hopefully we will never have to find out. + +************* Code Examples -------------- +************* Wrap all code examples at 70 characters to avoid horizontal scrollbars. @@ -122,29 +164,33 @@ Python examples: def get_answer(): return 42 + +****************** Externally Linking ------------------- +****************** * Prefer labels for well known subjects (ex: proper nouns) when linking: - .. code-block:: rest + .. code-block:: rest - Sphinx_ is used to document Python. + Sphinx_ is used to document Python. - .. _Sphinx: http://sphinx.pocoo.org + .. _Sphinx: http://sphinx.pocoo.org * Prefer to use descriptive labels with inline links instead of leaving bare links: - .. code-block:: rest +.. code-block:: rest - Read the `Sphinx Tutorial `_ + Read the `Sphinx Tutorial `_ * Avoid using labels such as "click here", "this", etc. preferring descriptive labels (SEO worthy) instead. + +******************************** Linking to Sections in The Guide --------------------------------- +******************************** To cross-reference other parts of this documentation, use the `:ref: `_ @@ -157,10 +203,12 @@ 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 `_ when making notes. @@ -180,8 +228,10 @@ Warnings: .. warning:: DON'T PANIC + +***** TODOs ------ +***** Please mark any incomplete areas of The Guide with a `todo directive `_. To @@ -192,5 +242,4 @@ documents or large incomplete sections. .. todo:: Learn the Ultimate Answer to the Ultimate Question - of Life, The Universe, and Everything - + of Life, The Universe, and Everything. pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy