Doc-SIG

Download

doc-sig@python.org

May 2012

1 participants
1 discussions

Style guide for documentation
by Benoît Bryon May 14, 2012

May 14, 2012

Hi, I am posting this message on docutils-users, sphinx-dev and doc-sig mailing lists: * @docutils-users, it's a proposal about some "restrictive" reStructuredText subset; * @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 packages. I started to write down conventions for Sphinx-based documentations at https://github.com/benoitbryon/documentation-style-guide-sphinx 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 practice). More explanations below. Story ===== 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 (docutils recommendation). * 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: https://github.com/benoitbryon/documentation-style-guide-sphinx Key features ============ * 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 inline hyperlinks. Feedback required ================= * 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 reStructuredText primer. * 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! Regards, -- Benoit Bryon

1 0