From fc721b08787c5a4782ed6dc7da78ec2433fe82a3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= <berrange@redhat.com>
Date: Mon, 18 Nov 2019 18:37:09 +0000
Subject: [PATCH] docs: add a minimal style guide for writing RST docs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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>
---
 docs/docs.html.in   |  3 +++
 docs/styleguide.rst | 66 +++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 69 insertions(+)
 create mode 100644 docs/styleguide.rst

diff --git a/docs/docs.html.in b/docs/docs.html.in
index f2721964b5..f441769617 100644
--- 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
index 0000000000..71f29320cb
--- /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
+   ^^^^^^^^^