[Doc-SIG] Style guide for documentation
benoit at marmelune.net
Mon May 14 09:46:08 CEST 2012
I am posting this message on docutils-users, sphinx-dev and doc-sig
* @docutils-users, it's a proposal about some "restrictive"
* @sphinx-dev, it's about Sphinx usage, i.e. best practices;
* @doc-sig, I wonder if it could be a PEP for documentation of Python
I started to write down conventions for Sphinx-based documentations at
I'd like to share this work, and I also need feedback.
I guess it could be compared to PEP-8, as a "style guide", but applied
to Sphinx-based documentations.
Python code can be valid even if it doesn't follow PEP-8; but Python
code should follow PEP-8 because it's the convention (and de facto best
More explanations below.
As a developer, I started using Sphinx some years ago. I contributed to
documentation of public or private projects using Sphinx. I also worked
in several teams with different background:
* private projects with Python developers working in the same company:
* Python projects
* PHP projects (yes, Sphinx is great to document a project, even if
is not a Python project)
* public projects, with people I didn't know before.
I feel we lack some restrictive convention:
* in each team, RST usage differ. As an example, one team choose .rst
extension (sphinx-quickstart's default), whereas another choose .txt
* often, RST usage differ within documents of a project, depending on
the original author: one developer uses "=" for first level of sections
whereas another uses "-" symbol.
* and many more use cases...
* as a new contributor, when I joined a project or team, I spent too much
time discovering conventions of the project. About documentation, I
had to read current project's documentation, and often there was no
convention at all.
* when I tried to propose conventions in a team, we had discussions.
Again it's time we'd better spend on development than on discussion.
I mean it's important to discuss and to share vision, but for this
particular topic we should have used an existing convention, we
shouldn't have asked.
* when I proposed the convention from one team to another, we discussed
it again. With other argues, and potentially a different convention at
the end :'(
That's why I started to write down conventions in a collaborative place,
so that every team can use it, reference it and contribute to it:
* more restrictive than reStructuredText: as told by the Zen of Python,
"There should be one-- and preferably only one --obvious way to do it."
* focus on use case: Sphinx-based documentation for a project.
As an example, use Sphinx's specific directives.
* provide more than just syntax. As an example, recommend usage of
target-notes directive at the end of a document, instead of using
* I wonder whether such conventions already exist or not.
* I wonder whether I should maintain a standalone convention or contribute
to Docutils, Sphinx or even Python via a PEP... In fact, I guess I'd
rather contribute, but I am not sure...
* maybe reStructuredText documentation could include some of the
proposed conventions as recommendations, so that users naturally
use these conventions.
* maybe Sphinx documentation could recommend some points in its
* maybe a PEP could recommend every Python developer to follow some
style guide when they write Sphinx documents.
* ... other suggestions are welcome!
* if you are interested in the project, use it or open issues!
More information about the Doc-SIG