documentation-style-guide-sphinx

documentation-style-guide-sphinx copied to clipboard

Produce clear guidelines about indentation

5

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...

benoitbryon

Github and .rst files

3

In the style guide, it says: - Some programs parse `.rst` with `rst2html`_, which cannot interpret some Sphinx's directives such as `code-block`. So readers using such programs actually lose some...

ardalis

I edited some of the words on the documentation

maintain53

Check PEP 12

1

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?

benoitbryon

A command to "beautify" RST files

2

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...

benoitbryon

Write a "style checker" extension for sphinx

1

``` 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...

benoitbryon

See http://restructuredtext-philosophy.readthedocs.org And http://ericholscher.com/blog/2012/jan/22/why-read-docs-matters/

benoitbryon

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...

benoitbryon

See http://www.python.org/dev/peps/pep-0287/ Is there any RST-style convention in this PEP?

benoitbryon

https://github.com/benoitbryon/documentation-style-guide-sphinx/blob/3c96a81bcd52ceb7d057f9bcf291c2148d9c736e/docs/style-guide.txt is getting quite long. Split it into several smaller documents.

benoitbryon