diff options
| author | Edoardo La Greca | 2025-05-05 20:18:14 +0200 |
|---|---|---|
| committer | Edoardo La Greca | 2025-05-05 20:18:14 +0200 |
| commit | 894c73faee37d0e996b4560e71a5d4b1be583be3 (patch) | |
| tree | 13f4d24126c0758ce066acb4bebd9a4275560f3a | |
| parent | 9e1e22061ad347a97ae1b92603cb45663c97ddc9 (diff) | |
fold readme
| -rw-r--r-- | doc/README | 30 |
1 files changed, 21 insertions, 9 deletions
@@ -2,7 +2,7 @@ Documentation ============= -In this directory you'll find pretty much all the documentation that needs to +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. @@ -11,12 +11,18 @@ 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 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`_. +- 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. +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: @@ -30,12 +36,16 @@ The allowed subset of reStructuredText only consists of the following. Each of t - 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 +- 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. +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:: +As for section titles, it is strongly advised to use them with the following +styles, in the following order:: ========= Section 1 @@ -50,7 +60,9 @@ As for section titles, it is strongly advised to use them with the following sty 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. +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 |