[libvirt] [PATCH v2 08/15] 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.
Signed-off-by: Daniel P. Berrangé <berrange(a)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 & 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
+ ^^^^^^^^^
--
2.23.0