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


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.


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
    And reference it in their project's documentation.


As explained in Status, priorities of this release are:

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