From 9e1e22061ad347a97ae1b92603cb45663c97ddc9 Mon Sep 17 00:00:00 2001 From: Edoardo La Greca Date: Mon, 5 May 2025 20:14:24 +0200 Subject: add documentation syntax --- doc/README | 51 ++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 50 insertions(+), 1 deletion(-) (limited to 'doc') diff --git a/doc/README b/doc/README index 8b60404..3c73417 100644 --- a/doc/README +++ b/doc/README @@ -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 + -- cgit v1.2.3