Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

Appearance settings

First pass at styleguide #60

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Dec 30, 2011
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 0 additions & 1 deletion 1 TODO.rst
Original file line number Diff line number Diff line change
@@ -1,4 +1,3 @@
* Establish "use this" vs "alternatives are...." recommendations
* Style Guide (for Guide)

.. todolist::
2 changes: 1 addition & 1 deletion 2 docs/contents.rst.inc
Original file line number Diff line number Diff line change
Expand Up @@ -84,4 +84,4 @@ Contibution notes and legal information are here (for those interested).
:maxdepth: 2

notes/contribute
notes/license
notes/license
2 changes: 2 additions & 0 deletions 2 docs/intro/duction.rst
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,8 @@ Introduction

.. todo:: write a general blurb introducing the Python language

.. _about-ref:

About This Guide
----------------

Expand Down
6 changes: 6 additions & 0 deletions 6 docs/notes/contribute.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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 <https://github.com/kennethreitz/python-guide/contributors>`_.

Style Guide
-----------

For all contributions, please follow the :ref:`guide-style-guide`.

.. _todo-list-ref:

Todo List
---------
Expand Down
132 changes: 132 additions & 0 deletions 132 docs/notes/styleguide.rst
Original file line number Diff line number Diff line change
@@ -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 <about-ref>`.

* 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 <http://sphinx.pocoo.org/rest.html?highlight=citations#citations>`_ 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 <http://sphinx.pocoo.org/tutorial.html>`_

* 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: <http://sphinx.pocoo.org/markup/inline.html#cross-referencing-arbitrary-locations>`_ 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 <http://sphinx.pocoo.org/rest.html#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 <http://sphinx.pocoo.org/ext/todo.html?highlight=todo#directive-todo>`_. 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
13 changes: 12 additions & 1 deletion 13 docs/writing/documentation.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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 <http://sphinx.pocoo.org/rest.html>`_ and the `reStructuredText Quick Reference <http://docutils.sourceforge.net/docs/user/rst/quickref.html>`_ should help you familiarize yourself with its syntax.

.. _reStructuredText: http://docutils.sourceforge.net/rst.html

Other Tools
:::::::::::
Expand Down
Morty Proxy This is a proxified and sanitized view of the page, visit original site.