Full Circle Magazine FR

Outils pour utilisateurs

Outils du site

Piste : • arduino • arduino • arduino • an_intro_to_sqlite • tuto_python • javascript • tuto-python
issue204:python

Différences

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

Lien vers cette vue comparative

Prochaine révision		Révision précédente
issue204:python [2024/04/28 07:17] – créée d52frissue204:python [2024/04/30 15:20] (Version actuelle) – andre_domenech
Ligne 1: Ligne 1:
-The Mysteries of the Sphinx+**The Mysteries of the Sphinx
  
 Greetings fellow Beings. Beaming from somewhere in time and space, I come again to, hopefully, provide some well needed information. Greetings fellow Beings. Beaming from somewhere in time and space, I come again to, hopefully, provide some well needed information.
Ligne 9: Ligne 9:
 Sphinx uses reStructured Text (rst) files to create HTML and, if desired, EPUB files, that can be easily included in your project. Sphinx uses reStructured Text (rst) files to create HTML and, if desired, EPUB files, that can be easily included in your project.
  
-So let’s jump right in and see how to get started.+So let’s jump right in and see how to get started.**
  
-Installing Sphinx+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
  
 First, the people at Sphinx suggest you use a virtual environment to install into. So, here are the steps. First, create the virtual environment and activate it. I usually create a directory in my project folder called “sphinx” and start from there. Open a terminal and use these steps. First, the people at Sphinx suggest you use a virtual environment to install into. So, here are the steps. First, create the virtual environment and activate it. I usually create a directory in my project folder called “sphinx” and start from there. Open a terminal and use these steps.
Ligne 32: Ligne 45:
  
 (.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
 accept a default value, if one is given in brackets). accept a default value, if one is given in brackets).
  
Ligne 52: Ligne 89:
 If the documents are to be written in a language other than English, If the documents are to be written in a language other than English,
 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.**
  
-For a list of supported codes, see+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
 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 72: Ligne 126:
  
 Now, change to the /docs/source/ folder. There are two files there that we will eventually need to edit. First is the index.rst file and the second is the conf.py file. If you plan to use any graphics files like screenshots of your applications, create an “images” folder in the source folder as well. So let’s change to the /docs/source folder. Now, change to the /docs/source/ folder. There are two files there that we will eventually need to edit. First is the index.rst file and the second is the conf.py file. If you plan to use any graphics files like screenshots of your applications, create an “images” folder in the source folder as well. So let’s change to the /docs/source folder.
 +
 +
 +(.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 (.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.
  
 (.venv)$ cat index.rst (.venv)$ cat index.rst
Ligne 96: Ligne 173:
 Notice at the top of the file is a line that starts with two dots. That is a commented line, so it will be ignored by Sphinx when creating the HTML file. Notice at the top of the file is a line that starts with two dots. That is a commented line, so it will be ignored by Sphinx when creating the HTML file.
  
-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.**
  
-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.+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.
  
 We’ll look at more directives in a little bit. We’ll look at more directives in a little bit.
Ligne 127: Ligne 227:
 build succeeded. build succeeded.
  
-The HTML pages are in docs/build/html.+The HTML pages are in docs/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.+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.
  
 Editing the Sphinx Document Editing the Sphinx Document
Ligne 140: Ligne 274:
  
 For the most part, the only thing that I’ve ever had to modify here is the next to last line, which sets the theme file for the output (we’ll discuss themes below). This line is by default… For the most part, the only thing that I’ve ever had to modify here is the next to last line, which sets the theme file for the output (we’ll discuss themes below). This line is by default…
 +
 +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' 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. 
  
 Images in your Sphinx Document Images in your Sphinx Document
Ligne 157: Ligne 306:
 .. image:: /images/sclbDemo20.png .. image:: /images/sclbDemo20.png
  
-   :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. 
  
-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.+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.
  
 Theming your Document Theming your Document
Ligne 169: Ligne 335:
 My favorite theme is the bizstyle, which is built in. There are 10 different themes that are already built into Sphinx. Any other themes that you might want to use, will have to be downloaded and installed. Some themes have special steps you need to do, so follow the instructions for that theme. My favorite theme is the bizstyle, which is built in. There are 10 different themes that are already built into Sphinx. Any other themes that you might want to use, will have to be downloaded and installed. Some themes have special steps you need to do, so follow the instructions for that theme.
  
-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. **
  
-Some other useful directives+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.
  
-There are WAY too many directives to try to cover them all here, and there are plenty of web sites that cover rst directives, so I’ll cover only a few of the ones that I commonly use.+Création d'un thème pour votre document
  
-Remember that how the directives look in the finished product depends on the theme you are using.+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
 +
 +There are WAY too many directives to try to cover them all here, and there are plenty of web sites that cover rst directives, so I’ll cover only a few of the ones that I commonly use.
 +
 +Remember that how the directives look in the finished product depends on the theme you are using.
  
 Admonitions Admonitions
Ligne 183: Ligne 360:
 I use admonitions often to highlight notes or warning statements. According to one of the rst directive web pages “Admonitions” ("safety messages" or "hazard statements") can appear anywhere an ordinary body element can. They contain arbitrary body elements. Typically, an admonition is rendered as an offset block in a document, sometimes outlined or shaded.” I use admonitions often to highlight notes or warning statements. According to one of the rst directive web pages “Admonitions” ("safety messages" or "hazard statements") can appear anywhere an ordinary body element can. They contain arbitrary body elements. Typically, an admonition is rendered as an offset block in a document, sometimes outlined or shaded.”
  
-Here is a simple note in code…+Here is a simple note in code…**
  
-.. Note::+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::
  
 The actual entry method depends on your Operating system. Some of the options might not be available on your system. The actual entry method depends on your Operating system. Some of the options might not be available on your system.
Ligne 200: Ligne 390:
    python colours1.py    python colours1.py
  
-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
  
 Like terminal code blocks, you can use language specific code blocks as well. Like terminal code blocks, you can use language specific code blocks as well.
Ligne 222: Ligne 431:
 - Calculated Closest Colour name - Calculated Closest Colour name
  
-- Calculated Best Colour for text on this colour.+- Calculated Best Colour for text on this colour.**
  
-Renders out like this…+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…
 As I said, there are many other directives you can use (and probably will) so in the next section I’ve provided a few of my favorite reStructured Text “go to” web pages. As I said, there are many other directives you can use (and probably will) so in the next section I’ve provided a few of my favorite reStructured Text “go to” web pages.
  
Ligne 240: Ligne 472:
  
  
-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.1714281470.txt.gz · Dernière modification : 2024/04/28 07:17 de d52fr