Différences

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

--- dev:python:sphinx:introduction [2025/02/27 11:20] – 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 153: / Ligne 178: @@
 </file>
+<note warning>
   * Attention aux guillemets arrières ;
   * Attention à l'espace avant ''<'' ;
   * Attention à l'underscore;
+</note>
+Pour la création d'un lien externe, on peut faire le choix de séparer la définition du lien et la cible :
+<code>
+Le paragraphe suivant contient seulement la `texte du lien`_
+La cible peut être définie plus loin dans le document
+Ici un autre paragraphe
+.. _texte du lien: https://cible.example.com
+</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:
+<code>
+.. _`mon-par`:
+Ici un simple paragraphe avant lequel on a placé  le label "mon-par".
+Plus loin dans ma documentation je peux faire faire référence au paragraphe précédent voir :ref:`mon par`
+</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 :
 <code>
 Liste à puce :
@@ Ligne 229: / Ligne 310: @@
   * Confère également la [[https://docutils.sourceforge.io/docs/ref/rst/directives.html#metadata-document-title|documentation en ligne des directives reStructuredTest]]
-===== Auto-documenter un package Python =====
-Sphinx a été conçu par la communauté Python pour les projets Python. Cependant il est utilisés par de nombreux autres projets opensource.
-Sphinx utilise l'extension **autodoc** pour inclure les docstrings dans la documentation à produire.
-reStructuredText est le formatage utilisé par défaut mais d'autre formatages peuvent être utilisés comme Markdown mais dans ce cas des extensions supplémentaires seront nécessaires.
-Pour documenter l'ensemble des classes d'un module:
-  * Le fichier conf.py doit avoir l'extension autodoc (''sphinx.ext.autodoc'') déclarée;
-  * Le fichier RST doit utiliser la directive automodule avec l'option '':members:''
-<code rst>
-.. automodule:: my_module_name
-   :members:
-</code>
 Introduire les images (png, jpg, gif)
@@ Ligne 281: / 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>
+===== Auto-documenter un package Python =====
+Sphinx a été conçu par la communauté Python pour les projets Python. Cependant il est utilisés par de nombreux autres projets opensource.
+Sphinx utilise l'extension **autodoc** pour inclure les docstrings dans la documentation à produire.
+reStructuredText est le formatage utilisé par défaut mais d'autre formatages peuvent être utilisés comme Markdown mais dans ce cas des extensions supplémentaires seront nécessaires.
+Pour documenter l'ensemble des classes d'un module:
+  * Le fichier conf.py doit avoir l'extension autodoc (''sphinx.ext.autodoc'') déclarée;
+  * Le fichier RST doit utiliser la directive automodule avec l'option '':members:''
+<code rst>
+.. automodule:: my_module_name
+   :members:
+</code>
 ===== L'extension doctest =====

wikinotes

Outils pour utilisateurs

Outils du site

Différences

Outils de la page