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. This month, I will present something that I’ve wanted to do for the last 8 months. As always, something would always get in the way and require my attention. This month, I purposefully refused to let anything take precedent over this topic. As you can see from this month’s title, it has to do with Sphinx. Not the massive limestone structure in Giza, but the Python software package used to create documentation. 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.
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. $ python -m venv .venv $ source .venv/bin/activate Next, use pip to install it into the virtual Python instance. (.venv)$ pip install sphinx Collecting sphinx… This takes only about a minute on my machine. Now check the version. (.venv) $ sphinx-build –version sphinx-build 7.2.6 Ok. Now, run the quickstart script which will ask questions about your project, then create the folders and the base files for you. (.venv)$ sphinx-quickstart docs 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 accept a default value, if one is given in brackets). Selected root path: docs You have two options for placing the build directory for Sphinx output. Either, you use a directory “_build” within the root path, or you separate “source” and “build” directories within the root path. > Separate source and build directories (y/n) [n]: y The project name will occur in several places in the built documentation. > Project name: sandbox > Author name(s): Greg Walters > Project release []: 0.1 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 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 https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language. > Project language [en]: Here is what the directory tree looks like. . └── docs ├── build ├── make.bat ├── Makefile └── source ├── conf.py ├── index.rst ├── _static └── _templates 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
Now, let's look and see what the index.rst file contains. (.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: It’s basic but that’s all we need to get started. 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.
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. Now, to create an HTML version of the documentation for our project, use the sphinx-build script, at least the first time. This should be done in the folder that you originally set up, which, in my case, was /sphinx. This tells Sphinx where the source folder is and the build folder. The build folder will hold our finished HTML files. So change back to the sphinx (parent of everything) folder. (.venv)$ sphinx-build -M html docs/source/ docs/build/ Running Sphinx v7.2.6 making output directory… done building [mo]: targets for 0 po files that are out of date writing output… building [html]: targets for 1 source files that are out of date updating environment: [new config] 1 added, 0 changed, 0 removed reading sources… [100%] index looking for now-outdated files… none found pickling environment… done checking consistency… done preparing documents… done copying assets… copying static files… done copying extra files… done done writing output… [100%] index generating indices… genindex done writing additional pages… search done dumping search index in English (code: en)… done dumping object inventory… done build succeeded. 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. Editing the Sphinx Document After trying many markdown editors, my favorite one to use is formiko. Formiko is included in most Linux distributions, but you can also find it at https://github.com/ondratu/formiko . This editor ticks all the boxes for me to be my ‘go to’ .rst editor. Automatic spell checking, syntax highlighting, it’s all there. It also handles .md files. The config.py file 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'
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 In order to use images in your Sphinx document, you will need to create a sub-folder to hold them in the source folder. Do NOT use spaces in your image filenames. Adding an image is pretty simple. You use the directive “.. image::” a space and then the filename with the path. So it would be something like this… .. image:: /images/startup.png There are options that include height, width, scale, and others. Here is an example of the image directive with the scale option. .. image:: /images/sclbDemo20.png :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. Theming your Document You will need to edit the config.py file in order to change the theme for your document. There are MANY themes available to suit your style. There is a web page that provides a gallery of the themes at https://sphinx-themes.org/#theme-mozilla-sphinx-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.
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 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 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…
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. Remember the spacing is VERY important both before and after the directive. Shown top right is what it looks like rendered using the bizstyle theme (but can look different in other themes). Code blocks You can use code blocks to highlight console commands or code snippets. Here is the directive for highlighting a terminal command. .. code:: console python colours1.py 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 Like terminal code blocks, you can use language specific code blocks as well. Create an instance of the widget giving it all of the information you might want use to customize the look of the widget (top right). And how it gets rendered is shown below. Bulleted lists Bulleted lists are REALLY easy in rst. Just place a dash in front of each item. From top to bottom on the left side of the image are: - Hex value - RGB Value - Calculated Closest Colour name - 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… 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. Helpful links 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 Looking at my page count, it’s about time for me to close for this month. 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 !