Full Circle Magazine FR

Outils pour utilisateurs

Outils du site

Piste : • python • python • python • python • python • python • python • python • python • an_intro_to_sqlite
issue204:python

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
issue204:python [2024/04/28 07:45] – d52frissue204:python [2024/04/30 15:20] (Version actuelle) – andre_domenech
Ligne 10: Ligne 10:
  
 So let’s jump right in and see how to get started.** So let’s jump right in and see how to get started.**
 +
 +Les mystères du Sphinx
 +
 +Salut mes amis. Venu de quelque part dans le temps et l'espace, je reviens pour, je l'espère, vous fournir quelques informations bien nécessaires.
 +
 +Ce mois-ci, je vais vous présenter quelque chose que je voulais faire depuis 8 mois. Comme toujours, quelque chose se mettait en travers de mon chemin et requérait mon attention. Ce mois-ci, j'ai délibérément refusé que quoi que ce soit prenne le pas sur ce sujet.
 +
 +Comme vous pouvez le voir dans le titre du mois, il s'agit de Sphinx. Non pas la structure massive en calcaire de Gizeh, mais le logiciel Python utilisé pour créer de la documentation.
 +
 +Sphinx utilise des fichiers rst (reStructured Text) pour créer des fichiers HTML et, si vous le souhaitez, des fichiers EPUB, qui peuvent être facilement inclus dans votre projet.
 +
 +Nous allons donc nous mettre au travail et voir comment commencer.
 +
  
 **Installing Sphinx **Installing Sphinx
Ligne 33: Ligne 46:
 (.venv)$ sphinx-quickstart docs (.venv)$ sphinx-quickstart docs
 Welcome to the Sphinx 7.2.6 quickstart utility.** Welcome to the Sphinx 7.2.6 quickstart utility.**
 +
 +Installation de Sphinx
 +
 +Tout d'abord, les gens de Sphinx vous suggèrent d'utiliser un environnement virtuel pour l'installation. Voici donc les étapes à suivre. Tout d'abord, créez l'environnement virtuel et activez-le. Je crée habituellement un répertoire dans mon dossier des projets appelé « sphinx » et je commence à partir de là. Ouvrez un terminal et procédez comme suit :
 +
 +$ python -m venv .venv
 +
 +$ source .venv/bin/activate
 +
 +Ensuite, utilisez pip pour l'installer dans l'instance virtuelle de Python.
 +
 +(.venv)$ pip install sphinx
 +Collecting sphinx...
 +
 +Cela ne prend qu'une minute sur ma machine. Maintenant, vérifiez la version.
 +
 +(.venv) $ sphinx-build --version
 +sphinx-build 7.2.6
 +
 +Ok. Maintenant, lancez le script de démarrage rapide qui vous posera des questions sur votre projet, puis créera les dossiers et les fichiers de base pour vous.
 +
 +(.venv)$ sphinx-quickstart docs
 +Bienvenue dans le kit de démarrage rapide de Sphinx 7.2.6.
 +
  
 **Please enter values for the following settings (just press Enter to **Please enter values for the following settings (just press Enter to
Ligne 53: Ligne 90:
 you can select a language here by its language code. Sphinx will then you can select a language here by its language code. Sphinx will then
 translate text that it generates into that language.** translate text that it generates into that language.**
 +
 +Veuillez saisir des valeurs pour les paramètres suivants (tapez Entrée pour accepter la valeur par défaut, lorsque celle-ci est indiquée entre crochets).
 +
 +Chemin racine sélectionné : docs
 +
 +Vous avez deux options pour l'emplacement du répertoire de build de la sortie de Sphinx.
 +Soit vous utilisez un répertoire "_build" dans le chemin racine, soit vous séparez les répertoires "source" et "build" dans le chemin racine.
 +
 +> Séparer les répertoires source et de sortie (y/n) [n]: y
 +
 +Le nom du projet apparaîtra à plusieurs endroits dans la documentation construite.
 +> Nom du projet: sandbox
 +> Nom(s) de(s) l'auteur(s): Greg Walters
 +> Version du projet []: 0.1
 +
 +Si les documents doivent être rédigés dans une langue autre que l’anglais, vous pouvez sélectionner une langue ici grâce à son identifiant. Sphinx utilisera ensuite cette langue pour traduire les textes que lui-même génère.
 +
  
 **For a list of supported codes, see **For a list of supported codes, see
 https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language. https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language.
-> Project language [en]:+> Project language [en]: 
  
 Here is what the directory tree looks like. Here is what the directory tree looks like.
Ligne 75: Ligne 129:
  
 (.venv)$ cd docs/source** (.venv)$ cd docs/source**
 +
 +Pour une liste des identifiants supportés, voir
 +https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language.
 +> Langue du projet [en]: fr
 +
 +Voici à quoi ressemble l'arborescence des répertoires.
 +
 +.
 +└── docs
 +    ├── build
 +    ├── make.bat
 +    ├── Makefile
 +    └── source
 +        ├── conf.py
 +        ├── index.rst
 +        ├── _static
 +        └─── _templates
 +
 +Maintenant, allez dans le dossier /docs/source/. Il y a deux fichiers que nous devrons éventuellement éditer. Le premier est le fichier index.rst et le second est le fichier conf.py. Si vous prévoyez d'utiliser des fichiers graphiques tels que des captures d'écran de vos applications, créez également un dossier « images » dans le dossier source. Passons donc au dossier /docs/source.
 +
 +
 +(.venv)$ cd docs/source
 +
  
 **Now, let's look and see what the index.rst file contains. **Now, let's look and see what the index.rst file contains.
Ligne 97: Ligne 174:
  
 Then at the bottom of the file are three lines that will be used to create the table of contents.** Then at the bottom of the file are three lines that will be used to create the table of contents.**
 +
 +Voyons maintenant ce que contient le fichier index.rst.
 +
 +(.venv)$ cat index.rst
 +
 +.. sandbox documentation master file, created by
 +   sphinx-quickstart on Sat Dec 16 10:04:46 2023.
 +   You can adapt this file completely to your liking, but it should at least
 +   contain the root `toctree` directive.
 +
 +Welcome to sandbox's documentation!
 +===================================
 +
 +.. toctree::
 +   :maxdepth: 2
 +   :caption: Contents:
 +
 +C'est basique mais c'est tout ce dont nous avons besoin pour commencer.
 +
 +Remarquez qu'en haut du fichier se trouve une ligne qui commence par deux points. Il s'agit d'une ligne commentée, qui sera donc ignorée par Sphinx lors de la création du fichier HTML.
 +
 +Ensuite, en bas du fichier, il y a trois lignes qui seront utilisées pour créer la table des matières.
 +
  
 **The two dots that start each of these lines is called a directive. Anytime you want to do something special, outside of bold or italic markings, which are the same commands as markdown (.md), so to set a word or phrase as bold you would wrap the phrase with two asterisks and italics would be just one. **The two dots that start each of these lines is called a directive. Anytime you want to do something special, outside of bold or italic markings, which are the same commands as markdown (.md), so to set a word or phrase as bold you would wrap the phrase with two asterisks and italics would be just one.
Ligne 128: Ligne 228:
  
 The HTML pages are in docs/build/html.** The HTML pages are in docs/build/html.**
 +
 +Les deux points qui commencent chacune de ces lignes s'appellent une directive. Chaque fois que vous voulez faire quelque chose de spécial, en dehors des marques de gras ou d'italique, qui sont les mêmes commandes que markdown (.md), donc pour mettre un mot ou une phrase en gras, vous devez entourer la phrase de deux astérisques et pour l'italique n'en faut qu'un.
 +
 +Nous verrons d'autres directives dans un instant.
 +
 +Maintenant, pour créer une version HTML de la documentation de notre projet, utilisez le script sphinx-build, au moins la première fois. Cela doit être fait dans le dossier que vous avez configuré à l'origine, qui, dans mon cas, était /sphinx. Cela indique à Sphinx où se trouve le dossier source et le dossier de compilation (build). Le dossier de compilation contiendra nos fichiers HTML finis. Retournez donc dans le dossier sphinx (parent de tout).
 +
 +(.venv)$ sphinx-build -M html docs/source/ docs/build/
 +
 +Sphinx v7.2.6 en cours d'exécution
 +chargement des traductions [fr]... fait
 +création du répertoire de sortie... fait
 +construction en cours [mo] : cibles périmées pour les fichiers po 0
 +Écriture... 
 +construction [html] : cibles périmées pour les fichiers sources 1
 +mise à jour de l'environnement : [nouvelle configuration] 1 ajouté(s), 0 modifié(s), 0 supprimé(s)
 +lecture des sources... [100%] index
 +Recherche des fichiers périmés... aucun résultat trouvé
 +Environnement de sérialisation... fait
 +vérification de la cohérence... fait
 +documents en préparation... fait
 +copie des ressources... Copie des fichiers statiques... fait
 +copie des fichiers complémentaires... fait
 +fait
 +Écriture... [100%] index
 +génération des index... genindex fait
 +Écriture des pages additionnelles... search fait
 +Export de l'index de recherche en français (code: fr)... fait
 +Export de l'inventaire des objets... fait
 +La compilation a réussi.
 +
 +Les pages HTML sont dans docs1/build/html.
 +
 +
  
 **That’s it. Now let’s look at getting it to actually create something. We’ll have to modify the index.rst file for that. **That’s it. Now let’s look at getting it to actually create something. We’ll have to modify the index.rst file for that.
Ligne 142: Ligne 276:
  
 html_theme = 'alabaster'** html_theme = 'alabaster'**
 +
 +C'est tout. Voyons maintenant comment faire pour qu'il crée réellement quelque chose. Pour cela, nous allons devoir modifier le fichier index.rst.
 +
 +Editer le document Sphinx
 +
 +Après avoir essayé de nombreux éditeurs markdown, mon préféré est formiko. Formiko est inclus dans la plupart des distributions Linux, mais vous pouvez également le trouver à https://github.com/ondratu/formiko.
 +
 +Cet éditeur remplit toutes les conditions pour être mon éditeur .rst « incontournable ». Vérification automatique de l'orthographe, mise en évidence de la syntaxe, tout y est. Il gère également les fichiers .md.
 +
 +Le fichier config.py
 +
 +Pour l'essentiel, la seule chose que j'ai eu à modifier ici est l'avant-dernière ligne, qui définit le fichier de thème pour la sortie (nous parlerons des thèmes plus loin). Cette ligne est par défaut :
 +
 +html_theme = 'alabaster'
 +
  
 **If you want a different built-in theme file, just change the word ‘alabaster’ to the theme of your choice. For many of the other themes, it is also this simple.  **If you want a different built-in theme file, just change the word ‘alabaster’ to the theme of your choice. For many of the other themes, it is also this simple. 
Ligne 158: Ligne 307:
  
    :scale: 50%**    :scale: 50%**
 +   
 +Si vous souhaitez un autre fichier de thème intégré, il vous suffit de remplacer le mot « alabaster » par le thème de votre choix. Pour la plupart des autres thèmes, c'est aussi simple que cela. 
 +
 +Images dans votre document Sphinx
 +
 +Afin d'utiliser des images dans votre document Sphinx, vous devrez créer un sous-dossier pour les contenir dans le dossier source. N'utilisez PAS d'espaces dans le nom de fichier de vos images.
 +
 +L'ajout d'une image est assez simple. Vous utilisez la directive « .. image:: », un espace, puis le nom du fichier avec le chemin d'accès. Cela donnerait donc quelque chose comme ceci :
 +
 +.. image:: /images/startup.png
 +
 +Il existe des options telles que la hauteur, la largeur, l'échelle et d'autres encore. Voici un exemple de directive image avec l'option scale.
 +
 +.. image:: /images/sclbDemo20.png
 +
 +   :scale : 50%
 +   
  
 **Notice the spacing. Spacing is VERY important in rst, so if there is an error in the build, that would be the first place to look. For the most part, any directive options are indented 4 spaces. Also note that when continuing your text after an image directive (or just about any directive), it is important to have at least one blank line between the directive and your next text. **Notice the spacing. Spacing is VERY important in rst, so if there is an error in the build, that would be the first place to look. For the most part, any directive options are indented 4 spaces. Also note that when continuing your text after an image directive (or just about any directive), it is important to have at least one blank line between the directive and your next text.
Ligne 170: Ligne 336:
  
 As I said above, you will have to edit the config.py file to set the theme that is used. ** As I said above, you will have to edit the config.py file to set the theme that is used. **
 +
 +Remarquez l'espacement. L'espacement est TRÈS important dans rst, donc s'il y a une erreur dans la compilation, c'est le premier endroit où regarder. En général, toutes les options de directives sont indentées de 4 espaces. Notez également que lorsque vous continuez votre texte après une directive image (ou à peu près n'importe quelle directive), il est important d'avoir au moins une ligne vide entre la directive et le texte suivant.
 +
 +Création d'un thème pour votre document
 +
 +Vous devrez éditer le fichier config.py afin de changer le thème de votre document. Il existe de NOMBREUX thèmes disponibles pour s'adapter à votre style. Une page Web présentant une galerie de thèmes est disponible à l'adresse suivante :
 +
 +https://sphinx-themes.org/#theme-mozilla-sphinx-theme .
 +
 +Mon thème préféré est bizstyle, qui est intégré. Il y a 10 thèmes différents qui sont déjà intégrés dans Sphinx. Tout autre thème que vous souhaiteriez utiliser devra être téléchargé et installé. Certains thèmes ont des étapes spéciales à suivre, alors suivez les instructions pour un tel thème.
 +
 +Comme je l'ai dit plus haut, vous devrez éditer le fichier config.py pour définir le thème utilisé.
 +
  
 **Some other useful directives **Some other useful directives
Ligne 182: Ligne 361:
  
 Here is a simple note in code…** Here is a simple note in code…**
 +
 +Quelques autres directives utiles
 +
 +Il y a BEAUCOUP trop de directives pour essayer de les couvrir toutes ici et il y a beaucoup de sites Web qui couvrent les premières directives ; aussi, je ne couvrirai que quelques-unes de celles que j'utilise couramment.
 +
 +N'oubliez pas que l'aspect des directives dans le produit fini dépend du thème que vous utilisez.
 +
 +Avertissements
 +
 +J'utilise souvent les avertissements pour mettre en évidence des notes ou des avertissements. Selon l'une des premières pages Web consacrées aux directives, les « avertissements (« messages de sécurité » ou « mentions de danger ») peuvent apparaître partout où un élément de corps ordinaire peut apparaître. Elles contiennent des éléments de corps arbitraires. En règle générale, un avertissement est présenté sous la forme d'un bloc décalé dans un document, parfois souligné ou ombré ».
 +
 +Voici une simple note en code :
 +
  
 **.. Note:: **.. Note::
Ligne 199: Ligne 391:
  
 And below is a screenshot of how it gets rendered.** And below is a screenshot of how it gets rendered.**
 +
 +.. Note::
 +
 +La méthode de saisie réellement utilisée dépend de votre système d'exploitation. Certaines options peuvent ne pas être disponibles dans votre système.
 +
 +N'oubliez pas que l'espacement est TRÈS important, tant avant qu'après la directive.
 +
 +L'image en haut à droite montre ce que cela donne avec le thème bizstyle (mais cela peut être différent avec d'autres thèmes).
 +
 +Blocs de code
 +
 +Vous pouvez utiliser des blocs de code pour mettre en évidence des commandes de la console ou des extraits de code. Voici la directive permettant de mettre en évidence une commande de terminal :
 +
 +.. code:: console
 +
 +   python colours1.py
 +
 +Et vous trouvez ci-dessous une capture d'écran de la façon dont cela est rendu.
 +
  
 **Language based code blocks **Language based code blocks
Ligne 221: Ligne 432:
  
 - Calculated Best Colour for text on this colour.** - Calculated Best Colour for text on this colour.**
 +
 +Blocs de code basés sur la langue
 +
 +Comme pour les blocs de code du terminal, vous pouvez également utiliser des blocs de code spécifiques à une langue.
 +
 +Créez une instance du widget en lui donnant toutes les informations que vous souhaitez utiliser pour personnaliser l'apparence du widget (en haut à droite).
 +
 +Le rendu est illustré ci-dessous.
 +
 +Listes à puces
 +
 +Les listes à puces sont VRAIMENT faciles à utiliser. Il suffit de placer un tiret devant chaque élément.
 +
 +Du haut en bas, côté gauche de l'image sont :
 +
 +- La valeur Hex 
 +
 +- La valeur RGB 
 +
 +- Nom de la couleur calculée au plus près
 +
 +- La meilleure couleur calculée pour du texte dans cette couleur.
 +
  
 **Renders out like this… **Renders out like this…
Ligne 239: Ligne 473:
  
 Until next time, as always; stay safe, healthy, positive and creative!** Until next time, as always; stay safe, healthy, positive and creative!**
 +
 +Le résultat est le suivant :
 +
 +Comme je l'ai dit, il existe de nombreuses autres directives que vous pouvez utiliser (et que vous utiliserez probablement). Dans la section suivante, je vous propose quelques-unes de mes pages Web en reStructured Text préférées.
 +
 +Liens utiles
 +
 +https://www.sphinx-doc.org/en/master/tutorial/first-steps.html
 +
 +https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#sections
 +
 +https://docutils.sourceforge.io/docs/user/rst/quickref.html
 +
 +https://docutils.sourceforge.io/docs/ref/rst/directives.html#top
 +
 +Au vu de mon nombre de pages, il est grand temps pour moi de terminer.
 +
 +Jusqu'à la prochaine fois, comme toujours, restez en sécurité, en bonne santé, positifs et créatifs !
 +
issue204/python.1714283137.txt.gz · Dernière modification : 2024/04/28 07:45 de d52fr