|
|
__[WIP: moamoak]__
|
|
|
|
|
|
This document describes how to write the documentation for Re2o. The principles stated here were voted by the stakeholders of the project. They should be followed as closely as possible when writing any form of documentation for the project.
|
|
|
|
|
|
The term "documentation" covers a variety of ways to describe and explain the behavior of Re2o (different levels of abstraction, different usages, different audience, ...) and in Re2o we should to use only a few of those ways. They are described and their context and rules are stated later in this document
|
|
|
|
|
|
|
|
|
# Language
|
|
|
|
|
|
All the documentation should be written in __English__. There is no exception to this rule. This decision comes from the following ideas:
|
|
|
* opening the project to anyone since English is the international language,
|
|
|
* avoiding a mix of English and another language in the code and the documentation. Because most of the used libraries' documentation is in English, some terms and names will obviously be written in English (variable names, concepts, functions, ...) and switching constently between two language makes the code and the documentation harder to understand.
|
|
|
|
|
|
|
|
|
# Wiki documentation
|
|
|
|
|
|
This wiki is the main place end-user documentation and developer's reference. Here are the rules about this documentation
|
|
|
|
|
|
|
|
|
## Naming
|
|
|
|
|
|
* There is a "Dev Documentation" (for development subjects) and a "User Documentation" (for end-user subjects) namespace that groups the pages together.
|
|
|
* For some big subjects that are easier to dive into when split into multiple pages, they can be grouped in a dedicated namespace (e.g. the `API` namespace groups the pages about the API whether it is a documentation for end-users or for developers).
|
|
|
* The gitlab's wiki is very sensible about the case of a page name. The rule for this wiki is to capitalize the first letter of every word in the page namespace and to capitalize only the first letter of the fisrt word for the page name.
|
|
|
* A space (` `) should be the prefered way to separate words in the name of the namespace. Even if sometimes the wiki replaces the spaces with `-` in the display.
|
|
|
* The name and namespace of a page should be written carefully upon creation because it is not easy to change manually all the references to a page afterward.
|
|
|
* Avoid changing a name's page after its creation to avoid broken links.
|
|
|
|
|
|
|
|
|
## Content
|
|
|
|
|
|
* The content of the documentation is written in markdown
|
|
|
* Obsolete information should be updated as fast as possible. If a whole page is obsolete, it might be enough to add a keyword at the top of the page to indicate it. E.g. `__[Obsolete]__`
|
|
|
* Work in progress should be indicated at the top of the page with a keyword. E.g. `__[WIP: <user_in_charge>]__`
|
|
|
* For long pages it might be a good idea to add a table of content with the links to the different section at the begining of the page. Unfortunately, there is no other ways of writing this "TOC" than manually with markdown links.
|
|
|
|
|
|
|
|
|
## General
|
|
|
|
|
|
* Every page should be accessible by starting at the [home page](home).
|
|
|
|
|
|
|
|
|
# Documentation in code
|
|
|
|
|
|
## Docstrings
|
|
|
|
|
|
TODO: translate this
|
|
|
|
|
|
Les docstrings servent a décrire la fonction (ce qu'elle fait mais aussi les arguments et la valeur retournée).
|
|
|
En théorie, on peut écrire ces infos (ou une partie de ces infos) de la manière qu'on veut. Mais (un jour peut-etre) on peut aussi générer de la documentation directement à partir de ce code (la plupart des docs python sont faites comme ça, c'est pour ça qu'elles se ressemblent toutes). Evidement il faut utiliser une syntaxe particulière pour que le générateur comprennent le code.
|
|
|
Pour Re2o, on a décidé (même si on l'a pas vraiment acté officiellement) d'utiliser la [notation de Google pour les docstrings](https://github.com/google/styleguide/blob/gh-pages/pyguide.md#38-comments-and-docstrings). En gros la syntaxe générale (tout n'est pas nécessaire ici) est la suivante
|
|
|
```python
|
|
|
def fct(arg1, arg2, arg3="plop", *args, **kwargs):
|
|
|
"""[une ou deux lignes (<80 chars) qui décriven ce que fait la fonction]
|
|
|
|
|
|
[une description un peu plus longue si besoin d'expliquer un comportement en détail ou
|
|
|
des options un peu difficiles. Cette description est optionnelle et peut s'étendre
|
|
|
sur plusieurs lignes (toujours <80 chars).
|
|
|
Les mot-clés suivants "Args", "Returns", "Raises" sont a écrire tels quels ils servent à
|
|
|
distinguer respectivement les sections qui décrivent les arguments pris par la fonction,
|
|
|
ce qu'elle retourne et les excpetions qui peuvent y être levées. Si il n'y a rien a mettre
|
|
|
dans la section, elle peut être omise.]
|
|
|
|
|
|
Args:
|
|
|
arg1: [une ou quelques phrases pour expliquer ce que fait arg1 et le type (bool, int, ...)
|
|
|
attendu si c'est pas évident. La description s'étend sur plusieurs lignes (on notera les
|
|
|
indetations de 4 espaces pour bien montrer que c'est la même description qui continue)]
|
|
|
arg2: [Une autre description pour cet argument]
|
|
|
arg3: [Dans le cas de valeurs par défaut, ne pas oublier de les préciser qqpart (une phrase
|
|
|
ou un truc du genre `(Default: "plop")` suffit)]
|
|
|
*args: [dans le cas d'argument "expanded list" on écrit bien l'astérisque]
|
|
|
**kwargs: [pareil pour les arguments "exapnded key-word list"]
|
|
|
|
|
|
Returns:
|
|
|
[Description de ce qui est retourné par la fonction + type de la variable si c'est pas
|
|
|
évident. Pareil ça peut s'écrire sur plusieurs lignes mais pas besoin d'en faire des
|
|
|
tartines pour que ce soit compréhensible en général.]
|
|
|
|
|
|
Raises:
|
|
|
ValueError: [ce que ça signifie quand cette exception est levée]
|
|
|
CustomException: [on peut aussi y décrire les informations qu'on peut y trouver et qui
|
|
|
décrive l'erreur. Surtout dans le cas d'exceptions customs qui utilise des objets]
|
|
|
mymodule.OtherException: [Après tu peux pas décrire toutes les exceptions possibles.
|
|
|
Il faut se limiter au trucs relatif à cette fonction. Une règle possible est de
|
|
|
documenter une exception que si tu as un "raises" dans ta fonction ou dans une sous
|
|
|
fonction que tu as aussi écrite et que tu utilises sans trop le dire.
|
|
|
"""
|
|
|
# do something in your fonction
|
|
|
# ...
|
|
|
# La docstring n'est pas faite pour expliquer l'implémentation ou un partie compliquée de
|
|
|
# l'algorithme. Celui qui utilise la fonction n'a pas besoin de savoir comment est foutu
|
|
|
# le code pour savoir comment utiliser la fonction (et ça c'est la docstring qui lui dit)
|
|
|
# Pour expliquer l'implémentation il vaut mieux mettre un commentaire avec # à l'endroit
|
|
|
# concerné et seuls ceux qui s'intéresseront au détail du code le verront
|
|
|
# ...
|
|
|
return response
|
|
|
```
|
|
|
|
|
|
Dans le cas où la fonction c'est juste un `return ....` simple la première ligne de la description peut être suffisante si les noms des arguments sont clairs. Exemple:
|
|
|
```python
|
|
|
def absolute(number):
|
|
|
"""Returns the absolute value of a number."""
|
|
|
if number >= 0 :
|
|
|
return number
|
|
|
else:
|
|
|
return -number
|
|
|
```
|
|
|
|
|
|
Dans le cas où la fonction est vraiment très simple et le nom de la fonction est explicite, tu peux même te passer de la docstring. Exemple:
|
|
|
```python
|
|
|
def ajoute2(number):
|
|
|
return number + 2
|
|
|
``` |
|
|
\ No newline at end of file |