blob: 3c73417a36583d7af27ac74de2d5179c6ff70b82 (
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
|
=============
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
|