External/libvirt
1
0
Fork 0
mirror of https://gitlab.com/libvirt/libvirt.git synced 2024-12-24 22:55:23 +00:00
Code Issues Packages Projects Releases Wiki Activity
8506afff7b
libvirt/docs/styleguide.rst
Daniel P. Berrangé fc721b0878 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>
2019-12-04 15:48:28 +00:00

979 B
Raw Blame History

Documentation style guide

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
^^^^^^^^^