Style guide for Sphinx-based documentations

This project is about coding standards for Sphinx [1]-based documentations.

This project focuses on conventions about what PEP 8 calls “style guide”.

Contents

Documentation style guide

This document focuses on style-guide. It is a kind of coding standards applied to documentation files. It is not about documentation content.

RestructuredText with Sphinx directives

This documentation uses Python-sphinx [1], which itself uses reStructuredText [2] syntax.

Filenames

Use only lowercase alphanumeric characters and - (minus) symbol.

Suffix filenames with the .txt extension.

Note

Usage of .rst extension is not recommended because:

  • RST files are human-readable text files. Most systems natively recognize the .txt extension and open these files with a text editor. This is a good choice.

  • Some programs parse .rst with rst2html [3], which cannot interpret some Sphinx’s directives such as code-block. So readers using such programs actually lose some content.

    As an example, well known Github [4] platform uses rst2html to render .rst files in its repository browser. Not only you lose content, you also lose features like links to lines.

  • When you need to read HTML builds of the documentation, best practice is to export documentation as static builds with sphinx-build command, then host and serve these builds as static files. For public projects, you may have a look at services like Read the docs [5].

Whitespaces

Indentation

Indent with 2 spaces.

Except:

  • toctree directive requires a 3 spaces indentation.
Blank lines

Two blank lines before overlined sections, i.e. before H1 and H2. One blank line before other sections. See Headings for an example.

One blank line to separate directives.

Some text before.

.. note::

  Some note.

Exception: directives can be written without blank lines if they are only one line long.

.. note:: A short note.

Line length

Limit all lines to a maximum of 79 characters.

Headings

Use the following symbols to create headings:

  1. # with overline
  2. * with overline
  3. =
  4. -
  5. ^
  6. "

As an example:

##################
H1: document title
##################

Introduction text.


*********
Sample H2
*********

Sample content.


**********
Another H2
**********

Sample H3
=========

Sample H4
---------

Sample H5
^^^^^^^^^

Sample H6
"""""""""

And some text.

If you need more than heading level 4 (i.e. H5 or H6), then you should consider creating a new document.

There should be only one H1 in a document.

Note

See also Sphinx’s documentation about sections [6].

Code blocks

Use the code-block directive and specify the programming language. As an example:

.. code-block:: python

  import this

Contributing

This document provides guidelines for people who want to contribute to the documentation-style-guide-sphinx project.

Create tickets

Please use the bugtracker [1] before starting some work:

  • check if the bug or feature request has already been filed. It may have been answered too!
  • else create a new ticket.
  • if you plan to contribute, tell us, but don’t wait for us! So that we are given an opportunity to discuss, join forces or give feedback as soon as possible.

Fork and branch

  • Work in forks and branches.
  • Prefix your branch with the ticket ID corresponding to the issue. As an example, if you are working on ticket #23 which is about headings convention, name your branch like 23-headings.

Download and install

System requirements:

  • Python [2] version 2.6 or 2.7.

    Note

    The provided Makefile uses python command. So you may use Virtualenv [3] to make sure the active python is the adequate one.

Execute:

git clone git@github.com/benoitbryon/documentation-style-guide-sphinx.git
cd documentation-style-guide-sphinx/
make install

If you cannot execute the Makefile, read it and adapt the few commands it contains in the install section to your needs.

Edit documents

They said “Eat your own dog food”, so follow style guide for Sphinx-based documentations [4].

In your commit messages, reference the ticket with some refs #TICKET-ID syntax.

Test and build

Tests and builds will automatically be triggered before commit:

If you want to run them manually, use the provided Makefile:

  • run tests with make tests
  • build documentation with make documentation-build
  • build README with make README-build

Share

  • Push your code
  • Submit a pull request

About

This section contains information about the documentation-project-style-guide-sphinx project itself.

Vision

About motivations and goals of the documentation-style-guide-sphinx project.

Context

In software development, documentation matters.

Sphinx [1] is a great documentation builder. It is community standard for Python [2] projects, but is not tied to Python and can be used to document almost everything. One of his strength is to use the reStructuredText [3] syntax, which focuses on simplicity and readability for humans.

As of may 2012, Sphinx’s reStructuredText primer [4] and docutils’ reStructuredText documentation [3] focus on syntax. They give examples, but they are quite permissive.

When developers contribute to projects, they read and write documentation. There are conventions about writing code, but there is no about writing documentation. So documentations, despite they are based on a common toolkit, are really heterogeneous:

  • the more developers, the more heterogeneous.
  • every project may use its own conventions.
Goal
Feature: public sphinx style guide

  In order to improve readability of documentation and make it consistent
  across the wide spectrum of Sphinx-based documentations
  As member of a development team
  I want to follow style conventions.

  Scenario: Adopt documentation-related conventions for a project
    Given a project
    And a team
    When the team chose Sphinx as documentation builder for project
    And the team needs conventions about the documentation
    Then team members follow the rules provided at
    http://documentation-style-guide-sphinx.readthedocs.org/
    And reference it in their project's documentation.
Priorities

As explained in Status, priorities of this release are:

  • write, try and maintain a public draft,
  • communicate about this project.

Status

Notes about the project status, until next release.

This is a proposal

Although applied on private or small projects, this style guide should be considered as a draft. It is not industry standard and have not been supported by some “big” projects.

However, you can already use it or provide feedback!

Status would change if, as examples:

  • additional users give feedback, i.e. if the project is not used by only its author ;)
  • additional contributors join the project, which should be equivalent to the previous point.
  • another project replaces this one.
Planning
  • Use the style guide in some projects managed by authors, contributors and early adopters.
  • Communicate and get feedback. Propose it to some visible projects such as:
  • Depending on the feedback and contributions, reconsider this project’s relevance, adapt goals and planning.

Authors and contributors

This project is released under the fair license. Here are project’s authors and contributors:

License

Copyright documentation-style-guide-sphinx authors and contributors.

Usage of the works is permitted provided that this instrument is retained with the works, so that any entity that uses the works is notified of this instrument.

DISCLAIMER: THE WORKS ARE WITHOUT WARRANTY.

Indices and tables