I think most people just follow the conventions of the python documentation project.
I actually don't think that this matters particularly much. Different projects have different needs, rst doesn't "care" too much which order you use underlines for headings as long as you do conceptually "wrong" things, which is what you care about from a documentation writing prospective. My day job is as a technical writer doing stuff with sphinx and restructured text (without Sphinx,) and the biggest barrier isn't the style of the text files, but the conceptual background to actually be able to write content that's relevant and appropriate, to say nothing of actual writing skills. A style guide would be one thing to spend a lot of time writing, that I don't think would have any real impact on the quality of documentation. Conversely, I think people might be able to create some style and perhaps even enforce it, but I don't think that would actually force people to write more clear sentences, to be able to structure text inductively, to use indexing more effectively, to effectively structure sections and documents in a hierarchy. So unlike python where PEP 8 actually makes python code more maintainable, and less prone to errors. Maybe it *would* be a good idea to increase the number of warnings, or include some sort of ``rstlint`` package that provided some sort of basic analysis of your RST source file. Which might help enforce local standards like: - Line wrapping conventions. - Numbers (i.e. depth) and types of outlining. - Use of admonitions - linking conventions. - footnote conventions. With the idea that consistency trumps any particular preference.... Cheers, sam On Sun, May 13, 2012 at 05:22:25PM +0200, Benoît Bryon wrote: > 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 five 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 > > -- > You received this message because you are subscribed to the Google Groups > "sphinx-dev" group. > To post to this group, send email to sphinx-dev@googlegroups.com. > To unsubscribe from this group, send email to > sphinx-dev+unsubscr...@googlegroups.com. > For more options, visit this group at > http://groups.google.com/group/sphinx-dev?hl=en. > -- Sam Kleinman (tychoish): - ga...@tychoish.com - tychoish <http://tychoish.com/> "don't get it right, get it written" -- james thurber
pgpKFyKR6KXDQ.pgp
Description: PGP signature
