benoitbryon / documentation-style-guide-sphinx

Coding standards for Sphinx-based documentations
26 stars 19 forks source link

Recommend an introduction before H2 #10

Open benoitbryon opened 12 years ago

benoitbryon commented 12 years ago

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.