Add test which checks that README is built without warnings or errors.

Import documentation conventions from some projects.

Including from https://github.com/gabrielfalcao/lettuce/blob/master/docs/dev/documentation.rst

Create project structure:

• README
• sphinx installation
• empty documentation for now

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

https://github.com/benoitbryon/documentation-style-guide-sphinx/blob/d16779976b3769f8713572e8cfa9a04cb5a53a78/README.rst doesn't follows style guide conventions. It should.

In order to make sure that README can be converted to HTML, add a script to build README.rst to HTML.

Add a scripts/git/pre-commit.
Activate it with buildout.
Update README/contribute accordingly.

Pre-commit hook runs tests: see #17 and #18

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 example toctree directive doesn't work with 2 spaces but seems to work with 3 or 4 spaces.
2. in code-blocks, it's a pain to deal with mixed indentation.
   As an example:

The following block is indented with 2 spaces.
.. code-block:: python

  def some_intendation():
      """This comment is indented with 4 spaces."""

Python convention is to use 4 spaces. Since most Sphinx projects are about Python projects, Python code-blocks are a really common use case. So 4 space indentation may be useful for many users (most of them?).

Another common use case for code-blocks is sh or bash... 4 spaces doesn't hurt in that case.

Add test which checks that documentation build doesn't generate errors or warnings.

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

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

  As an example, well known Github_ platform uses rst2html
  to render .rst files in its repository browser. Not only you lose
  content, you also lose features like links to lines.

This doesn't appear to be the case (any longer). I uploaded a test here:
https://github.com/ardalis/Docs/blob/master/docs/github-test.rst

And it renders just fine (images are broken, but that's because I didn't copy them - code blocks render just fine, and no content is lost). When editing the file, it opens in a plain text editor, showing all RST markup, so again there doesn't appear to be any risk of loss of content when using .rst extension files and Github.

Can you comment and/or update the style guide?

Thanks!
Steve

Proof of concept implementation could be:

Feature: script which applies style guide recommendations on existing RST files
  In order to apply style guide conventions on existing RST files
  As a documentation writer
  I want to run a script which does most of the work automatically

  Scenario: apply style guide recommendations on an existing RST file
    Given a file named `example.txt`
    And this file contains valid RST content
    And the title of the document doesn't use `#` (sharp) character with overline
    And other titles don't use `#` (sharp) character
    When I run some `rst-beautify` script with `example.txt` as argument
    Then the file is modified in place and the title of the document uses  `#` (sharp) character with overline.

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 #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 to create a separate package (in another repository).

See

=> The standard is .txt. This convention is on docutils website!
=> Don't use Sphinx's default which is .rst!

There are some RST conventions in PEP 12.
Adopt some of them? or ask the PEP author to adoptt the conventions here?

• Currently, this is not software but content... add a license like Creative commons?
• If #5 is implemented, add a license like BSD or something.

See https://github.com/benoitbryon/documentation-best-practices/issues/3

In RST documents, if you use H2 just after H1 like this...

##########
Some title
##########


********
Subtitle
********

Here some text.

... then it means that there is no introduction text.

Should be:

##########
Some title
##########

This document illustrates usage of introduction text.


********
Subtitle
********

Here some text.

Rename it to something like "documentation-style-guide-sphinx"?

README contains important information such as:

• about
• contribution guidelines
• vision...

Merge it in documentation, so that it appears on static builds (i.e. on ReadTheDocs service).