Benoît Bryon
Benoît Bryon
Issues with 2 spaces: 1. It's a pain to have several indentation levels in a same RST document while editing it, because the TAB shorcut gives wrong results. As an...
There are some RST conventions in [PEP 12](http://www.python.org/dev/peps/pep-0012/). Adopt some of them? or ask the PEP author to adoptt the conventions here?
Proof of concept implementation could be: ``` Gherkin Feature: script which applies style guide recommendations on existing RST files In order to apply style guide conventions on existing RST files...
``` gherkin Feature: validate documentation style In order to validate documentation against style guide conventions As a documentation writer I want to run scripts that give me feedback about style...
See http://restructuredtext-philosophy.readthedocs.org And http://ericholscher.com/blog/2012/jan/22/why-read-docs-matters/
See #17 and #18: these tests are for this "documentation-style-guide-sphinx" project. But they would be useful for any Sphinx-based documentation project. Is it possible to distribute these tests? May require...
See http://www.python.org/dev/peps/pep-0287/ Is there any RST-style convention in this PEP?
https://github.com/benoitbryon/documentation-style-guide-sphinx/blob/3c96a81bcd52ceb7d057f9bcf291c2148d9c736e/docs/style-guide.txt is getting quite long. Split it into several smaller documents.
See https://github.com/benoitbryon/documentation-style-guide-sphinx/blob/d16779976b3769f8713572e8cfa9a04cb5a53a78/docs/style-guide.txt#L24 and http://docutils.sourceforge.net/FAQ.html#what-s-the-standard-filename-extension-for-a-restructuredtext-file => The standard is .txt. This convention is on docutils website! => Don't use Sphinx's default which is .rst!
See https://github.com/benoitbryon/documentation-best-practices/issues/3 In RST documents, if you use H2 just after H1 like this... ``` rst ########## Some title ########## ******** Subtitle ******** Here some text. ``` ... then it...