Tous les fichiers qui contiendront votre texte doivent avoir l’extension : rst

Et, ils doivent tous être dans le dossier : /docs/source

reStructuredText

Avant de modifier le fichier index.rst, via un simple éditeur de texte, il faut connaître quelques règles. Les plus importantes vous ont déjà été présentées (dans la page d’accueil de ce tutoriel). Il en existe d’autres. Le lien ci-dessous vous les présente toutes :

https://www.sphinx-doc.org/fr/master/usage/restructuredtext/index.html

Autres liens :

Outre le gras, l’italique, les titres, les liens, les notes, les images, … vous pouvez également présenter des …

Formules mathématiques

https://www.sphinx-doc.org/fr/master/usage/restructuredtext/directives.html#math

\[\begin{split}(a + b)^2 &= (a + b)(a + b) \\ &= a^2 + 2ab + b^2\end{split}\]
\[nombre~d'or = \varphi = \frac{1+\sqrt{5}}{2} = 1,618...\]
(1)\[e^{i\pi} + 1 = 0\]

Euler’s identity, equation (1), was elected one of the most beautiful mathematical formulas.

Directives

Une ligne réelle est une suite d’octects terminée par un code (de fin de ligne). Une ligne réelle peut être affichée (à l’écran) sur plusieurs lignes, selon la taille de l’écran.

Les trois caractères d’une ligne (réelle) sont significatifs. Ils lui permettent de déterminer s’il s’agit d’un texte simple, d’une directive ou d’un bloc rattaché à sa directive .

Dans le premier cas, on commence à écrire dès le début de la ligne.

Dans le deuxième cas, on saisira deux points, suivis d’un espace, suivi du nom de la directive, suivi de deux doubles points (.. nom-de-la-directive::)

Enfin, dans le troisième cas, on se décalera toujours d’un espace (au minimum) pour rester dans le bloc lié à la directive.

Note

Pour éviter un message d’avertissement lors de la génération d’un fichier :

  • Le décalage doit être un nombre constant d’espaces.

  • L’ensemble (directive + le bloc qui lui est attaché) doit être précédé et suivi d’une ligne vide.

Quelques noms de directives

  • note

  • image

  • math

  • …

Un bloc peut contenir un ensemble (directive et son bloc). Ainsi, une note peut contenir une image.

ReST directives

Directives ajoutées par Sphinx

make html