diff options
| author | Edoardo La Greca | 2025-05-05 20:14:24 +0200 |
|---|---|---|
| committer | Edoardo La Greca | 2025-05-05 20:14:24 +0200 |
| commit | 9e1e22061ad347a97ae1b92603cb45663c97ddc9 (patch) | |
| tree | c0a38c8abcf6916b7da388954d3a10a707e0ab19 | |
| parent | f06d08c65fdb67a9ab97851e79f0e045050156bf (diff) | |
add documentation syntax
| -rw-r--r-- | doc/README | 51 |
1 files changed, 50 insertions, 1 deletions
@@ -1,8 +1,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 tell already. +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 + |