wikinotes

Outils pour utilisateurs

Outils du site

Piste : • 240_between • interruptions • buildchain-esp32 • 230_clause_fetch
dev:python:sphinx:introduction

Différences

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

Lien vers cette vue comparative

Les deux révisions précédentesRévision précédente
Prochaine révision		Révision précédente
dev:python:sphinx:introduction [2025/02/26 20:37] – yoanndev:python:sphinx:introduction [2025/02/27 15:25] (Version actuelle) – yoann
Ligne 2: Ligne 2:
  
  
-====== sphinx : Générateur de documentation =====+====== Sphinx : Générer de la documentation =====
  
-Sphinx est un programme dédié à la génération de tous types de documentation associée à un projet: +Sphinx est un programme dédié à la génération de tout type de documentation associée à un projet: 
-  * La documentation de référence (documentation des modules, classes et APIs);+  * La documentation de référence du code (documentation des modules, classes et APIs);
   * les tutoriaux (documentation à objectifs pédagogiques);   * les tutoriaux (documentation à objectifs pédagogiques);
   * Les How-To (documentation ayant pour objet la résolution de problèmes);   * Les How-To (documentation ayant pour objet la résolution de problèmes);
   * Les documents explicatifs ayant pour objectif de faire connaître ou de justifier certains choix.   * Les documents explicatifs ayant pour objectif de faire connaître ou de justifier certains choix.
  
-Souvent on pense à Sphinx comme à un outil de génération de documentation technique pour Python capable d'extraire les docstrings du code afin de produire une documentation de référence en HTML.+Souvent on pense à Sphinx comme à un outil de génération de documentation technique pour Python capable d'extraire les **docstrings** du code afin de produire une documentation de référence en HTML.
  
-Plus généralement Sphinx peut prendre en entrée tout type de document texte et produire une sortie lisible.+Plus généralement Sphinx peut prendre en entrée tout type de documents textes et produire une sortie parmi un ensemble de formats lisible.
  
 En général les fichiers texte en entrées utilisent le formatage **reStructredText** et la sortie produite par Sphinx est un ensemble de documents formatés en HTML. En général les fichiers texte en entrées utilisent le formatage **reStructredText** et la sortie produite par Sphinx est un ensemble de documents formatés en HTML.
Ligne 76: Ligne 76:
  
  
-===== Ajouter des pages =====+===== Ajouter un document =====
  
   * Créer un fichier .rst dans le dossier de la documentation ;   * 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> <note>
Ligne 94: Ligne 94:
 </file> </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:: .. toctree::
    :maxdepth: 2    :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 '':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 ;   * 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.
  
  
 ===== Introduction à la syntaxe reStructuredText ===== ===== Introduction à la syntaxe reStructuredText =====
  
-La syntaxe reStructuredText, bien que proche de Markdown, est plus complète mais également plus stricte.+La [[https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html|syntaxe reStructuredText utilisée par Sphinx]], bien que proche de Markdown, est plus complète mais également plus stricte.
  
 Pour l'essentiel : Pour l'essentiel :
Ligne 121: Ligne 122:
 </code> </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> <code>
Ligne 137: Ligne 160:
 </code> </code>
  
 +On définit un niveau de titre en le surlignant avec les caractères spéciaux. Par défaut, les niveaux de titres ne sont pas associés à un caractère particulier, c'est  l'ordre d'usage qui permet à Sphinx de déterminer le niveau de titre.
  
-Pour une URL :+Par convention dans [[https://devguide.python.org/documentation/markup/#sections| le guide de la documentation du code en Python]] on trouve : 
 + 
 +  * ''#'' pour les parties 
 +  * ''*'' pour les chapitres 
 +  * ''='' pour les sections 
 +  * ''-'' pour les sous-sections 
 +  * ''^'' pour les sous-sous-sections 
 +  * ''"'' pour les paragraphes 
 + 
 +==== Liens externes ==== 
 + 
 +Pour une URL (externe) :
 <file> <file>
 Syntaxe d'écrite d'une URL `mon titre <https://example.com>`_ Syntaxe d'écrite d'une URL `mon titre <https://example.com>`_
 </file> </file>
  
 +<note warning>
   * Attention aux guillemets arrières ;   * Attention aux guillemets arrières ;
   * Attention à l'espace avant ''<'' ;   * Attention à l'espace avant ''<'' ;
   * Attention à l'underscore;   * 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 : Les listes :
 +
 <code> <code>
 Liste à puce : Liste à puce :
Ligne 155: Ligne 246:
  
   * Une sous-liste   * Une sous-liste
-  * notez bien le saut de ligne avec la liste principale,+  * Notez bien le saut de ligne avec la liste principale,
     ça ne marchera pas si vous l'oubliez !     ça ne marchera pas si vous l'oubliez !
 +    Ce même élément s'étend sur 3 lignes.
  
 * un dernier élément * un dernier élément
Ligne 217: Ligne 309:
   * Le site officiel de Sphinx propose une [[https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html|introduction plus complète à reStructuredText]]   * Le site officiel de Sphinx propose une [[https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html|introduction plus complète à reStructuredText]]
   * Confère également la [[https://docutils.sourceforge.io/docs/ref/rst/directives.html#metadata-document-title|documentation en ligne des directives reStructuredTest]]   * Confère également la [[https://docutils.sourceforge.io/docs/ref/rst/directives.html#metadata-document-title|documentation en ligne des directives reStructuredTest]]
 +
 +
 +Introduire les images (png, jpg, gif)
 +
 +<code>
 +Voici une image :
 +
 +.. figure:: ./images/image.png
 +
 +Voici un autre image avec quelques paramètres en plus :
 +
 +.. figure:: ./images/image.png
 +   :alt: Texte alternatif
 +   :target: https://example.com/
 +   :width: 400px
 +   :align: center
 +
 +   Texte affiché sous l'image (même indentation)
 +
 +</code>
 +
 +Pour les tableaux, on définit les cellules telles qu'on souhaite les voir s'afficher :
 +
 +<code>
 ++-----------+-----------+-----------+
 +| Heading 1 | Heading 2 | Heading 3 |
 ++===========+===========+===========+
 +| Hello     | World     |           |
 ++-----------+-----------+-----------+
 +| foo       |                       |
 ++-----------+          bar          |
 +| baz       |                       |
 ++-----------+-----------------------+
 +</code>
 +
 +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>
 +
  
  
Ligne 236: Ligne 378:
 </code> </code>
  
-Introduire les images (png, jpg, gif) 
  
-<code> 
-Voici une image : 
- 
-.. figure:: ./images/image.png 
- 
-Voici un autre image avec quelques paramètres en plus : 
- 
-.. figure:: ./images/image.png 
-   :alt: Texte alternatif 
-   :target: http://blog.flozz.fr/ 
-   :width: 400px 
-   :align: center 
- 
-   Texte affiché sous l'image 
-</code> 
  
 ===== L'extension doctest ===== ===== L'extension doctest =====
dev/python/sphinx/introduction.1740602269.txt.gz · Dernière modification : 2025/02/26 20:37 de yoann

Outils de la page

Sauf mention contraire, le contenu de ce wiki est placé sous les termes de la licence suivante : GNU Free Documentation License 1.3
GNU Free Documentation License 1.3 Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki