Différences

Ci-dessous, les différences entre deux révisions de la page.

--- dev:python:sphinx:introduction [2025/02/27 13:24] – yoann
+++ dev:python:sphinx:introduction [2025/02/27 15:25] (Version actuelle) – yoann
@@ Ligne 76: / Ligne 76: @@
-===== Ajouter des pages =====
+===== Ajouter un document =====
   * Créer un fichier .rst dans le dossier de la documentation ;
-  * Référencer la nouvelle page dans l'index.
+  * Référencer ce nouveau document en l'ajoutant à l'index.
 <note>
@@ Ligne 94: / Ligne 94: @@
 </file>
-Le fichier index.rst a le contenu suivant
+Le fichier index.rst contient le sommaire généré de la facon suivante :
-<code python>
+<code>
 .. toctree::
    :maxdepth: 2
@@ Ligne 106: / Ligne 107: @@
   * Le paramètre '':maxdepth:'' spécifie le nombre de niveaux de titres à afficher dans la table. Avec une valeur 1 seul les titres de page seront présents dans l'index.
   * Le paramètre '':caption:'' permet de définir le titre à afficher au dessus du sommaire ;
-  * Attention a bien laisser la ligne vide qui sépare les paramètres de la directive de son contenu.
+  * Attention a bien laisser la ligne vide séparant les paramètres de la directive de son contenu.
@@ Ligne 121: / Ligne 122: @@
 </code>
-Pour les titres :
+==== Les commentaires ====
+Commentaire simple
+<code>
+.. Un commentaire sur toute la ligne courante
+Le texte présent est un autre bloc (un paragraphe).
+Le commentaire ci-dessus n'est pas visible à la génération du document.
+</code>
+Commentaire multi-lignes :
+<code>
+..
+  Un commentaire sur plusieurs lignes
+  Le texte de même indentation reste un commentaire
+  Un autre paragraphe dans le même commentaire
+Le texte ici n'est plus un commentaire
+</code>
+==== Les titres et sections ====
 <code>
@@ Ligne 147: / Ligne 170: @@
   * ''^'' pour les sous-sous-sections
   * ''"'' pour les paragraphes
+==== Liens externes ====
 Pour une URL (externe) :
 <file>
@@ Ligne 171: / Ligne 196: @@
 </code>
+==== Les références croisées ====
 Une des forces de Sphinx réside dans sa gestion des **références croisées**. De nombreux éléments de la documentation peuvent être désignés/référencés par des liens internes (référence).
+Tous les détails concerant les **cross-references** sont abordés dans la [[https://www.sphinx-doc.org/en/master/usage/referencing.html#ref-role|documentation Sphinx sur les références croisées]].
 De manière générale on place un **label** en amont du bloc:
@@ Ligne 183: / Ligne 213: @@
 </code>
+==== Lien vers un document ====
+Pour créer une référence vers un autre document :
+<code>
+.. lien vers un document
+Retour à l' :doc:`index`
+.. lien vers un document avec définition du texte du lien
+Retour à la :doc:`page d'accueil </index>`
+</code>
+==== Lien de téléchargement ====
+Pour créer un lien de téléchargement désignant un fichier ressource présent dans l'arborescence de la documentation :
+<code>
+Télécharger le GIF Hamtaro :download:`image GIF </docs/_static/images/hamtaro_bubble.gif>`
+</code>
+==== Les listes ====
 Les listes :
@@ Ligne 293: / Ligne 345: @@
 En plus de la syntaxe propre à reStructuredTest, Sphinx introduit des éléments spécifiques à la documentation du code
+==== Métadonnées HTML ====
+On peut également introduire des métadonnées pour la génération des documents en HTML :
+<code>
+.. meta::
+   :keywords: Bareos
+   :keywords lang=en: backup, restore
+   :keywords lang=fr: sauvegarde, restauration
+</code>

wikinotes

Outils pour utilisateurs

Outils du site

Différences

Outils de la page