mirror of
https://gitlab.com/libvirt/libvirt.git
synced 2024-12-25 01:34:11 +03:00
fc721b0878
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>
67 lines
979 B
ReStructuredText
67 lines
979 B
ReStructuredText
=========================
|
|
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
|
|
^^^^^^^^^
|