docs: add a minimal style guide for writing RST docs

Most importantly we document the required heading markup so that we get
consistency across the docs. Also mention that docs should have a table
of contents if they have headings & are likely longer than one page of
text.

The 3-space indent rule may sound wierd, but that's what python has
recommended and thus what tools like pandoc emit. Rather than try to
reindent things to 4-space, just accept this RST norm.

Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>

diff --git a/docs/docs.html.in b/docs/docs.html.in
index f2721964b55f72e0c0843dab761fdfd56fb71f40..f441769617cef04d929a781f6291e2a4dc68e039 100644 (file)
--- a/docs/docs.html.in
+++ b/docs/docs.html.in
@@ -135,6 +135,9 @@
         <dt><a href="hacking.html">Contributor guidelines</a></dt>
         <dd>General hacking guidelines for contributors</dd>
 
+        <dt><a href="styleguide.html">Docs style guide</a></dt>
+        <dd>Style guidelines for reStructuredText docs</dd>
+
         <dt><a href="strategy.html">Project strategy</a></dt>
         <dd>Sets a vision for future direction &amp; technical choices</dd>
 

diff --git a/docs/styleguide.rst b/docs/styleguide.rst
new file mode 100644 (file)
index 0000000..71f2932
--- /dev/null
+++ b/docs/styleguide.rst
@@ -0,0 +1,66 @@
+=========================
+Documentation style guide
+=========================
+
+.. contents::
+
+The following documents some specific libvirt rules for writing docs in
+reStructuredText
+
+Table of contents
+=================
+
+Any document which uses headings and whose content is long enough to cause
+scrolling when viewed in the browser must start with a table of contents.
+This should be created using the default formatting:
+
+::
+
+   .. contents::
+
+
+Whitespace
+==========
+
+Blocks should be indented with 3 spaces, and no tabs
+
+
+Headings
+========
+
+RST allows headings to be created simply by underlining with any punctuation
+characters. Optionally the text may be overlined to.
+
+For the sake of consistency, libvirt defines the following style requirement
+which allows for 6 levels of headings
+
+::
+
+   =========
+   Heading 1
+   =========
+
+
+
+   Heading 2
+   =========
+
+
+
+   Heading 3
+   ---------
+
+
+
+   Heading 4
+   ~~~~~~~~~
+
+
+
+   Heading 5
+   .........
+
+
+
+   Heading 6
+   ^^^^^^^^^