blob: 7cb47e1f6e09dde3fa8ed9d4b8a72ee7f3c51284 (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
|
=============
Documentation
=============
In this directory you'll find pretty much all the documentation that needs to
be provided in addition to what the code and its comments can tell you already.
If you have a question, head to FAQ.
Rules while writing
===================
All documentation (i.e. all files in this directory, including this) must
follow these rules:
- All lines must fold to 80 characters and lines must break in a space
character, not within words. A reasonable exception is made for URLs, which
are kept whole.
- For better clarity and consistency, documentation must use a common markup
language. The markup language of choice is a subsect of the syntactic
structures offered by `reStructuredText`_.
The allowed subset of reStructuredText only consists of the following. Each of
them must be used whenever it's possible and appropriate.
- paragraphs
- some inline markup:
- emphasis
- strong emphasis
- inline literals
- section titles (up to 4 nested)
- bullet, enumerated, and definition lists
- literal blocks
- block quotes
- grid and simple tables
- footnotes (and their inline references)
- citations (and their inline references)
- hyperlink targets (and their inline references) except for anonymous
hyperlinks and indirect hyperlink references
- standalone hyperlinks (only on their own line)
Every syntactic structure which is only (or mainly) useful to the text when
it's rendered or processed through a program has been stripped off. Elements
which hurt readability when read as plain text have also been removed.
As for section titles, it is strongly advised to use them with the following
styles, in the following order::
=========
Section 1
=========
Section 2
=========
Section 3
---------
Section 4
~~~~~~~~~
and to keep two empty lines above each section title, with an exception for the
first section title which should occur only once at the beginning of the
document.
.. _reStructuredText: https://docutils.sourceforge.io/rst.html
|