diff --git a/docs/notes/styleguide.rst b/docs/notes/styleguide.rst index 2bbc8878c..626d4a8ba 100644 --- a/docs/notes/styleguide.rst +++ b/docs/notes/styleguide.rst @@ -4,23 +4,34 @@ The Guide Style Guide ===================== -As with all documentation, having a consistent formating 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 approriate. +As with all documentation, having a consistent formating 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 +approriate. -The Guide is written as :ref:`restructuredtext-ref`. +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 by 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 by 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 --------- -Stride 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. -* 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 conjuction with Python (ex: Git, Github, Databases), reference by linking to useful resouces and describe why it's useful to Python. +Stride 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. +* 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 conjuction + with Python (ex: Git, Github, Databases), reference by linking to useful + resouces and describe why it's useful to Python. * When in doubt, ask. Headings @@ -49,11 +60,19 @@ Sub section headings:: Very Deep ~~~~~~~~~ - + +Prose +----- + +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. + + Code Examples ------------- -Wrap all code examples within 70 characters to avoid horizontal scrollbars. +Wrap all code examples at 70 characters to avoid horizontal scrollbars. Command line examples:: @@ -65,17 +84,21 @@ Command line examples:: Be sure to include the ``$`` prefix before each line. Python interpreter examples:: - + Label the example:: - + + .. code-block:: python + >>> import this Python examples:: Descriptive title:: + .. code-block:: python + def get_answer(): - return 42 + return 42 Externally Linking ------------------ @@ -86,16 +109,20 @@ Externally Linking .. _Sphinx: http://sphinx.pocoo.org -* Prefer to use descriptive labels with inline links instead of leaving bare links:: +* Prefer to use descriptive labels with inline links instead of leaving bare + links:: Read the `Sphinx Tutorial `_ -* Avoid using labels such as "click here", "this", etc. preferring decriptive labels (SEO worthy) instead. +* Avoid using labels such as "click here", "this", etc. preferring + decriptive labels (SEO worthy) instead. Linking to Sections in The Guide -------------------------------- -To cross-reference other parts of this documentation, use the `:ref: `_ keyword and labels. +To cross-reference other parts of this documentation, use the `:ref: +`_ +keyword and labels. To make reference labels more clear and unique, always add a ``-ref`` suffix:: @@ -107,26 +134,31 @@ 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. +Make use of the appropriate `admonitions directives +`_ when making notes. Notes:: - - .. note:: + + .. 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. Warnings:: - + .. warning:: DON'T PANIC TODOs ----- -Please mark any incomplete areas of The Guide with a `todo directive `_. To avoid cluttering the :ref:`todo-list-ref`, use a single ``todo`` for stub documents or large incomplete sections. +Please mark any incomplete areas of The Guide with a `todo directive +`_. To +avoid cluttering the :ref:`todo-list-ref`, use a single ``todo`` for stub +documents or large incomplete sections. :: - .. todo:: - Learn the Ultimate Answer to the Ultimate Question - of Life, The Universe, and Everything \ No newline at end of file + .. todo:: + Learn the Ultimate Answer to the Ultimate Question + of Life, The Universe, and Everything +