From b9d9a1a22a83839c53910b6b46fc608584cf5629 Mon Sep 17 00:00:00 2001 From: Dan Crosta Date: Fri, 30 Dec 2011 19:47:18 -0500 Subject: [PATCH] wrap to 78chars, cleanup some trailing whitespace --- 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 2bbc887..33c804c 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 `. +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. +* 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,7 +60,7 @@ Sub section headings:: Very Deep ~~~~~~~~~ - + Code Examples ------------- @@ -65,9 +76,9 @@ Command line examples:: Be sure to include the ``$`` prefix before each line. Python interpreter examples:: - + Label the example:: - + >>> import this Python examples:: @@ -75,7 +86,7 @@ Python examples:: Descriptive title:: def get_answer(): - return 42 + return 42 Externally Linking ------------------ @@ -86,16 +97,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 +122,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 +