From 909bd3963534325a45b35486e1f2873ccf856c0f Mon Sep 17 00:00:00 2001 From: Mike Thornton Date: Fri, 30 Dec 2011 16:36:19 -0600 Subject: [PATCH] First pass at styleguide --- TODO.rst | 1 - docs/contents.rst.inc | 2 +- docs/intro/duction.rst | 2 + docs/notes/contribute.rst | 6 ++ docs/notes/styleguide.rst | 132 +++++++++++++++++++++++++++++++++ docs/writing/documentation.rst | 13 +++- 6 files changed, 153 insertions(+), 3 deletions(-) create mode 100644 docs/notes/styleguide.rst diff --git a/TODO.rst b/TODO.rst index af1790d76..af9093b7f 100644 --- a/TODO.rst +++ b/TODO.rst @@ -1,4 +1,3 @@ * Establish "use this" vs "alternatives are...." recommendations -* Style Guide (for Guide) .. todolist:: \ No newline at end of file diff --git a/docs/contents.rst.inc b/docs/contents.rst.inc index 515c0a402..6355029f8 100644 --- a/docs/contents.rst.inc +++ b/docs/contents.rst.inc @@ -84,4 +84,4 @@ Contibution notes and legal information are here (for those interested). :maxdepth: 2 notes/contribute - notes/license + notes/license diff --git a/docs/intro/duction.rst b/docs/intro/duction.rst index a96ca8862..0bd99e755 100644 --- a/docs/intro/duction.rst +++ b/docs/intro/duction.rst @@ -3,6 +3,8 @@ Introduction .. todo:: write a general blurb introducing the Python language +.. _about-ref: + About This Guide ---------------- diff --git a/docs/notes/contribute.rst b/docs/notes/contribute.rst index e5e66cc01..3caf7583e 100644 --- a/docs/notes/contribute.rst +++ b/docs/notes/contribute.rst @@ -8,6 +8,12 @@ issue on GitHub_. To submit patches, please send a pull request on GitHub_. Once your changes get merged back in, you'll automatically be added to the `Contributors List `_. +Style Guide +----------- + +For all contributions, please follow the :ref:`guide-style-guide`. + +.. _todo-list-ref: Todo List --------- diff --git a/docs/notes/styleguide.rst b/docs/notes/styleguide.rst new file mode 100644 index 000000000..2bbc8878c --- /dev/null +++ b/docs/notes/styleguide.rst @@ -0,0 +1,132 @@ +.. _guide-style-guide: + +===================== +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. + +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:: 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. +* When in doubt, ask. + +Headings +-------- + +Use the following styles for headings. + +Chapter title:: + + ######### + Chapter 1 + ######### + +Page title:: + + =================== + Time is an Illusion + =================== + +Section headings:: + + Lunchtime Doubly So + ------------------- + +Sub section headings:: + + Very Deep + ~~~~~~~~~ + +Code Examples +------------- + +Wrap all code examples within 70 characters to avoid horizontal scrollbars. + +Command line examples:: + + .. code-block:: console + + $ run command --help + $ ls .. + +Be sure to include the ``$`` prefix before each line. + +Python interpreter examples:: + + Label the example:: + + >>> import this + +Python examples:: + + Descriptive title:: + + def get_answer(): + return 42 + +Externally Linking +------------------ + +* Prefer labels for well known subjects (ex: proper nouns) when linking:: + + Sphinx_ is used to document Python. + + .. _Sphinx: http://sphinx.pocoo.org + +* 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. + +Linking to Sections in The Guide +-------------------------------- + +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:: + + .. _some-section-ref: + + Some Section + ------------ + +Notes and Warnings +------------------ + +Make use of the appropriate `admonitions directives `_ when making notes. + +Notes:: + + .. 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. + +:: + + .. todo:: + Learn the Ultimate Answer to the Ultimate Question + of Life, The Universe, and Everything \ No newline at end of file diff --git a/docs/writing/documentation.rst b/docs/writing/documentation.rst index 094a01343..d1c4658c4 100644 --- a/docs/writing/documentation.rst +++ b/docs/writing/documentation.rst @@ -59,9 +59,20 @@ Multi-line docstrings: :: Sphinx ------ -Sphinx (http://sphinx.pocoo.org) is a tool which converts documentation in the reStructured text markup language into a range of output formats including HTML, LaTeX (for printable PDF versions), manual pages and plain text. +Sphinx_ is a tool which converts documentation in the :ref:`restructuredtext-ref` markup language into a range of output formats including HTML, LaTeX (for printable PDF versions), manual pages and plain text. +.. note:: This Guide is built with Sphinx_ +.. _Sphinx: http://sphinx.pocoo.org + +.. _restructuredtext-ref: + +reStructuredText +---------------- + +Most Python documentation is written with reStructuredText_. The `reStructuredText Primer `_ and the `reStructuredText Quick Reference `_ should help you familiarize yourself with its syntax. + +.. _reStructuredText: http://docutils.sourceforge.net/rst.html Other Tools :::::::::::