From c12757a6732f04580b50b0a60bd5e0852ae2535f Mon Sep 17 00:00:00 2001 From: daniel Date: Mon, 26 Nov 2018 17:44:02 +0100 Subject: [PATCH 1/3] style guide update --- docs/notes/styleguide.rst | 68 +++++++++++++++++++++++++-------------- 1 file changed, 44 insertions(+), 24 deletions(-) diff --git a/docs/notes/styleguide.rst b/docs/notes/styleguide.rst index 619c6daff..233b49e8b 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 @@ -19,8 +19,10 @@ The Guide is written as :ref:`restructuredtext-ref`. .. 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 +38,15 @@ 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. + +Blank lines +=========== + +Two blank lines before a heading and one after the heading. + + Headings --------- +======== Use the following styles for headings. @@ -45,34 +54,40 @@ 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 +100,9 @@ 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,8 +138,9 @@ Python examples: def get_answer(): return 42 + Externally Linking ------------------- +================== * Prefer labels for well known subjects (ex: proper nouns) when linking: @@ -136,15 +153,16 @@ Externally Linking * 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 +175,11 @@ 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 +199,10 @@ Warnings: .. warning:: DON'T PANIC + +***** TODOs ------ +***** Please mark any incomplete areas of The Guide with a `todo directive `_. To @@ -193,4 +214,3 @@ documents or large incomplete sections. .. todo:: Learn the Ultimate Answer to the Ultimate Question of Life, The Universe, and Everything - From 567fdda5cb659765d633fa9001d017828b7186d1 Mon Sep 17 00:00:00 2001 From: daniel Date: Tue, 27 Nov 2018 06:14:21 +0100 Subject: [PATCH 2/3] structure fix, style edit, style applied to page --- docs/notes/styleguide.rst | 73 +++++++++++++++++++++++++++------------ 1 file changed, 51 insertions(+), 22 deletions(-) diff --git a/docs/notes/styleguide.rst b/docs/notes/styleguide.rst index 233b49e8b..23794d651 100644 --- a/docs/notes/styleguide.rst +++ b/docs/notes/styleguide.rst @@ -13,11 +13,13 @@ 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. ********* @@ -28,25 +30,46 @@ Strive to keep any contributions relevant to the :ref:`purpose of The Guide `. * Avoid including too much information on subjects that don't directly - relate to Python development. +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. +Be sure to describe what and why you are linking. * `Cite `_ - references where needed. +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. +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. +********** +Whitespace +********** + +Indentation +=========== + +4 spaces, no tabs. + Blank lines =========== -Two blank lines before a heading and one after the heading. +* 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. @@ -86,8 +109,10 @@ 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 @@ -101,8 +126,9 @@ 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. @@ -139,30 +165,32 @@ Python examples: 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: +links: .. code-block:: rest Read the `Sphinx Tutorial `_ * Avoid using labels such as "click here", "this", etc. preferring - descriptive labels (SEO worthy) instead. +descriptive labels (SEO worthy) instead. +******************************** Linking to Sections in The Guide -================================ +******************************** To cross-reference other parts of this documentation, use the `:ref: `_ @@ -178,8 +206,9 @@ To make reference labels more clear and unique, always add a ``-ref`` suffix: ============ +****************** Notes and Warnings -================== +****************** Make use of the appropriate `admonitions directives `_ when making notes. @@ -213,4 +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. From 30a3504e4473d9fa059da68e3bde915fefdfa344 Mon Sep 17 00:00:00 2001 From: daniel Date: Tue, 27 Nov 2018 06:17:44 +0100 Subject: [PATCH 3/3] quick fix --- docs/notes/styleguide.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/notes/styleguide.rst b/docs/notes/styleguide.rst index 23794d651..7da4cd2b3 100644 --- a/docs/notes/styleguide.rst +++ b/docs/notes/styleguide.rst @@ -30,14 +30,14 @@ Strive to keep any contributions relevant to the :ref:`purpose of The Guide `. * Avoid including too much information on subjects that don't directly -relate to Python development. + 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. + Be sure to describe what and why you are linking. * `Cite `_ -references where needed. + 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. + 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. @@ -57,7 +57,7 @@ Blank lines * 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*. + lines after it*. .. code-block:: reStructuredText @@ -178,14 +178,14 @@ Externally Linking .. _Sphinx: http://sphinx.pocoo.org * Prefer to use descriptive labels with inline links instead of leaving bare -links: + links: .. code-block:: rest Read the `Sphinx Tutorial `_ * Avoid using labels such as "click here", "this", etc. preferring -descriptive labels (SEO worthy) instead. + descriptive labels (SEO worthy) instead. ********************************