Full Circle Magazine FR

Cette page est en lecture seule. Vous pouvez afficher le texte source, mais ne pourrez pas le modifier. Contactez votre administrateur si vous pensez qu'il s'agit d'une erreur.
**More Mysteries of the Sphinx

Greetings fellow Sentient Lifeforms. Beaming yet again from somewhere in time and space, I come again to, hopefully, provide more well needed information. (If you are not a Sentient Lifeform, I do not intend to withhold this from you, so feel free to attempt to read this.)

This month's article was inspired by one of the PAGE users on the PAGE Discord forum and someone whom I consider a good friend, Professor Roberto Machorro Mejía, who started using PAGE last school year. He teaches at UNAM, a public university, the largest in Mexico. He was using PAGE to create a GUI for a project he and his students were working on. Long story short, he has been reading Full Circle Magazine for a while now and he sent me a note that he really enjoyed my article on Sphinx in last month's issue. He was wondering, however, if Sphinx worked directly on a source file. So, I decided to write about how to make this happen.**

D'autres mystères du Sphinx

Bonjour à tous les êtres vivants sensibles. Rayonnant une fois de plus de quelque part dans le temps et l'espace, je reviens pour, je l'espère, fournir plus d'informations bien nécessaires. (Si vous n'êtes pas une forme de vie sensible, je n'ai pas l'intention de vous cacher ces informations, alors n'hésitez pas à essayer de les lire).

L'article de ce mois-ci a été inspiré par l'un des utilisateurs de PAGE sur le forum Discord de PAGE et quelqu'un que je considère comme un bon ami, le professeur Roberto Machorro Mejía, qui a commencé à utiliser PAGE l'année scolaire dernière. Il enseigne à l'UNAM, une université publique, la plus grande du Mexique. Il utilisait PAGE pour créer une interface graphique dans le cadre d'un projet sur lequel il travaillait avec ses étudiants. Pour faire court, il lit le magazine Full Circle depuis un certain temps et il m'a envoyé un message pour me dire qu'il avait beaucoup aimé mon article sur Sphinx dans le numéro du mois dernier. Il se demandait toutefois si Sphinx travaillait directement sur un fichier source. J'ai donc décidé d'écrire sur la façon d'y parvenir.


**I created a dummy program that really does nothing much but has functions that have Python Docstrings that can be used by Sphinx to “automatically document” the functions in the generated HTML or EPUB files.

Creating the docstrings that are needed to do this is very simple, but you need to remember to use the docstrings in every function, no matter how simple. If you don’t, you’ll probably have to go back and update the source file.

So, it all starts with your source code. If you use PAGE to create your GUI program, you don’t need to do anything to the PAGE .tcl file or the Python GUI.py file. The only file you need to concern yourself with is the support.py file.

One other thing to note, I’m using the bizstyle theme for Sphinx. If you decide to use a different Sphinx theme, your document won’t match the images that I’ve included here.**

J'ai créé un programme factice qui ne fait pas grand-chose, mais dont les fonctions ont des Docstrings Python qui peuvent être utilisées par Sphinx pour « documenter automatiquement » les fonctions dans les fichiers HTML ou EPUB générés.

La création des docstrings nécessaires à cette fin est très simple, mais vous devez vous rappeler d'utiliser les docstrings dans chaque fonction, aussi simple soit-elle. Si vous ne le faites pas, vous devrez probablement revenir en arrière et mettre à jour le fichier source.

Tout commence donc avec votre code source. Si vous utilisez PAGE pour créer votre programme de GUI, vous n'avez rien à faire dans le fichier PAGE .tcl ou dans le fichier Python GUI.py. Le seul fichier dont vous devez vous préoccuper est le fichier support.py.

Une autre chose à noter, j'utilise le thème bizstyle pour Sphinx. Si vous décidez d'utiliser un thème Sphinx différent, votre document ne correspondra pas aux images que j'ai incluses ici.


**The docstring

The docstring is simply a section of your source code that starts and ends with three double quotes and in between is pretty much free-form information. However, for Sphinx to grab the information, there needs to be a few special lines. Here (next page, top right) is a snippet of what you can expect to provide…

Of course the first line is the function definition. Then we start the docstring with the three double quotes.

The next line is a description of what the function is for, which must be a single line. Then any parameters need to be documented using the format:

:param {parameter name}:  description of parameter

:type {parameter name}:   parameter type

…

Then what the function returns:

:return: description of the return value**

La docstring

La docstring est simplement une section de votre code source qui commence et se termine par trois guillemets doubles et entre les deux se trouvent des informations libres. Cependant, pour que Sphinx puisse saisir l'information, il doit y avoir quelques lignes spéciales. Voici (page suivante, en haut à droite) un extrait de ce que vous pouvez vous attendre à fournir.

Bien sûr, la première ligne est la définition de la fonction. Ensuite, nous commençons la docstring avec les trois doubles guillemets.

La ligne suivante est une description de l'objet de la fonction, qui doit être d'une seule ligne. Ensuite, tous les paramètres doivent être documentés en utilisant le format :

:param {parameter name}:  description du paramètre

:type {parameter name}:   type de paramètre

...

Ensuite, ce que la fonction renvoie :

:return: description de la valeur retournée


**If there is more than one parameter, simply repeat the param and type keys.

For more information on Docstrings, you can follow this link https://peps.python.org/pep-0257/#abstract

Doing it Manually

Of course you can do the documentation of your functions and methods manually. I'll create a "dummy" entry for a fictitious **Sphinx** document.

This is just the description that I would put into the fictitious index.rst file…

One of the best things about the program is for the user to have the ability to change themes at any time to any theme in the theme folder. Of course, these are all .tcl themes. Use the load_tcl_themes function to generate a list of all of the themes, then load this into a TCombobox values property. Then bind the virtual **<<ComboboxSelected>>** event to the TCombobox providing a callback function whenever the user selects something from the TCombobox list. Here is the ``sphinxDemo1_support.on_ComboSelect()`` function

Now we describe the function using the .. py:function:: directive.**

S'il y a plus d'un paramètre, il suffit de répéter les clés param et type.

Pour plus d'informations sur les Docstrings, vous pouvez suivre ce lien https://peps.python.org/pep-0257/#abstract

Le faire manuellement

Bien entendu, vous pouvez documenter manuellement vos fonctions et méthodes. Je vais créer une entrée « factice » pour un document **Sphinx** fictif.

Voici la description que je mettrais dans le fichier fictif index.rst...

L'un des aspects les plus intéressants du programme est que l'utilisateur a la possibilité de changer de thème à tout moment et de choisir n'importe quel thème dans le dossier des thèmes. Bien entendu, il s'agit de thèmes .tcl. Utilisez la fonction load_tcl_themes pour générer une liste de tous les thèmes, puis chargez-la dans une propriété TCombobox values. Liez ensuite l'événement virtuel **<<ComboboxSelected>>** à la TCombobox en fournissant une fonction de rappel chaque fois que l'utilisateur sélectionne quelque chose dans la liste de la TCombobox. Voici la fonction « sphinxDemo1_support.on_ComboSelect() ».

Maintenant, nous décrivons la fonction en utilisant la directive ... py:function::.


**You can see that this is very similar to the docstring information that I suggested you place into the source code, but manually entered into the index.rst Sphinx file (right).

Here (next page, top right) is how it will look in your HTML file.
That’s a lot of work to do, especially if the code has already been documented using docstrings.


Doing it Automatically

In order to take advantage of the automatic documentation abilities of Sphinx, you will need to do a little bit of preparation. You will need to modify the conf.py file and add at least one extra .rst file to the /sphinx/docs/source folder.

The changes need to go into the conf.py file. These lines (right) need to go somewhere around line 16.

The most important line is the one that starts with

sys.path.append()**

Vous pouvez voir qu'il s'agit d'une information très similaire à la docstring que je vous ai suggéré de placer dans le code source, mais saisie manuellement dans le fichier index.rst de Sphinx (à droite).

Voici (page suivante, en haut à droite) à quoi cela ressemblera dans votre fichier HTML.
C'est beaucoup de travail, surtout si le code a déjà été documenté à l'aide des docstrings.


Le faire automatiquement

Afin de profiter des capacités de documentation automatique de Sphinx, vous devez faire un peu de préparation. Vous devrez modifier le fichier conf.py et ajouter au moins un fichier .rst supplémentaire dans le dossier /sphinx/docs/source.

Les modifications doivent être apportées au fichier conf.py. Ces lignes (à droite) doivent être placées aux alentours de la ligne 16.

La ligne la plus importante est celle qui commence par

sys.path.append()


**This is the fully qualified path to your source code. You don’t need to enter the filename(s) at this point, just the path.

The other important part is the extensions section. You will need to have all four lines in the list.

Now you just need to add one line to your index.rst file for each function you want Sphinx to document.

.. autofunction:: sphinxDemo1_support.load_tcl_themes

Of course, you can add text before or after this line, but here is what the output will look like. (I included the first line, just to make it flow better). See image bottom left.

Adding an Autosummary

You need to create an extra .rst file named something like “api.rst”. In it you place just a few lines…**

Voici le chemin d'accès complet à votre code source. Vous n'avez pas besoin d'entrer le(s) nom(s) de fichier à ce stade, mais seulement le chemin.

L'autre partie importante est la section des extensions. Vous devez avoir les quatre lignes dans la liste.

Il ne vous reste plus qu'à ajouter une ligne à votre fichier index.rst pour chaque fonction que vous voulez que Sphinx documente.

.. autofonction: : sphinxDemo1_support.load_tcl_themes

Bien sûr, vous pouvez ajouter du texte avant ou après cette ligne, mais voici à quoi ressemblera la sortie. (J'ai inclus la première ligne, juste pour améliorer la fluidité). Voir l'image en bas à gauche.

Ajouter un résumé automatique //d52fr : à traiter comme un titre//

Vous devez créer un fichier .rst supplémentaire nommé quelque chose comme « api.rst ». Dans ce fichier, vous placez quelques lignes...


**API
======

.. autosummary::

   :toctree: generated

   sphinxDemo1_support

The final addition to your index.rst file needs to tell Sphinx to include the api.rst file. This is actually just a single line in the TableOfContentsTree section (which is near the end, just before the Indices and tables section).

.. toctree::

   :maxdepth: 2

   :caption: Contents:

   api

Notice that the only line in bold is the one that adds the api.rst file, and this is the one you need to add. You don’t have to include the .rst extension.

When you run your next build, you will see the addition to the bottom of the main page…**

API
======

.. autosummary::

   :toctree: generated

   sphinxDemo1_support

Le dernier ajout à votre fichier index.rst doit indiquer à Sphinx d'inclure le fichier api.rst. Il s'agit en fait d'une simple ligne dans la section TableOfContentsTree (qui se trouve vers la fin, juste avant la section Indices et tables).

.. toctree::

   :maxdepth: 2

   :caption: Contents:

   api

Remarquez que la seule ligne en gras est celle qui ajoute le fichier api.rst et c'est celui que vous devez ajouter. Vous n'avez pas besoin d'inclure l'extension .rst.

Lorsque vous lancerez votre prochaine compilation, vous verrez l'ajout au bas de la page principale...


**And when you click on the hyperlink in red, you will be directed to the api listing.

You can see that the two functions that I included with the .. py:function:: directive, are hyperlinked to the section that I added in the main document.

You can create a special .rst file that holds all the ..py:function:: directives to make it easier to add more information about each of those functions if you wish. Simply place the extra .rst file in the same section before your api.rst inclusion in the toctree section.

One word of warning here. If you are using Formiko as your .rst editor, you will end up with a number of warnings in the preview window. These are usually a “System Message: Error/3” warning. You can usually ignore these messages, since they refer to unknown directives. I’m fairly certain that the folks at Formiko will get these added or addressed in the near future.**

Et lorsque vous cliquez sur l'hyperlien en rouge, vous serez dirigé vers la liste des api.

Vous pouvez voir que les deux fonctions que j'ai incluses avec la directive ... py:function:: sont hyperliées à la section que j'ai ajoutée dans le document principal.

Vous pouvez créer un fichier .rst spécial qui contient toutes les directives ... py:function:: pour faciliter l'ajout d'informations supplémentaires sur chacune de ces fonctions si vous le souhaitez. Placez simplement le fichier .rst supplémentaire dans la même section avant votre inclusion de api.rst dans la section toctree.

Un mot d'avertissement ici. Si vous utilisez Formiko comme éditeur de fichiers .rst, vous obtiendrez un certain nombre d'avertissements dans la fenêtre de prévisualisation. Il s'agit généralement d'un avertissement de type « System Message : Error/3 ». Vous pouvez généralement ignorer ces messages, puisqu'ils font référence à des directives inconnues. Je suis presque certain que les gens de Formiko ajouteront ou corrigeront ces messages dans un avenir proche.


**Conclusion

If you are getting a number of errors when you do your build, the first thing that you should look at is the directive formatting and the line(s) following the directive. Sphinx is VERY picky about formatting and white space. It’s usually something very simple.

I’ve created a repository as I often do. I included the Sphinx index.rst and conf.py file to make it easy for you to have a reference to this month’s information.

The repository is located at https://github.com/gregwa1953/FCM-205. This repository is a little different from my normal ones. There are two folders that hold the demo files. The first is the code folder which holds all of the files for the demo program, including the PAGE .tcl file and the docs folder that has the Sphinx documentation HTML file. The other folder is the SphinxSource folder which holds the images folder, api.rst, index.rst and the conf.py files.

I also included the generated HTML file in the code/docs/html file as well as enabled the help button in the sample program to display the HTML on demand.

Until next time, as always; stay safe, healthy, positive and creative!**

Conclusion

Si vous obtenez un certain nombre d'erreurs lors de votre compilation, la première chose que vous devriez regarder est le formatage de la directive et la ou les lignes qui suivent la directive. Sphinx est TRÈS pointilleux sur le formatage et l'espace blanc. C'est généralement quelque chose de très simple.

J'ai créé un dépôt comme je le fais souvent. J'ai inclus les fichiers Sphinx index.rst et conf.py pour que vous puissiez facilement avoir une référence aux informations de ce mois.

Le dépôt est situé à l'adresse https://github.com/gregwa1953/FCM-205. Ce dépôt est un peu différent de mes dépôts habituels. Il y a deux dossiers qui contiennent les fichiers de démonstration. Le premier est le dossier code qui contient tous les fichiers du programme de démonstration, y compris le fichier PAGE .tcl et le dossier docs qui contient le fichier HTML de la documentation Sphinx. L'autre dossier est le dossier SphinxSource qui contient le dossier des images, les fichiers api.rst, index.rst et conf.py.

J'ai également inclus le fichier HTML généré dans le fichier code/docs/html et j'ai activé le bouton d'aide dans le programme d'exemple pour afficher le HTML à la demande.

Jusqu'à la prochaine fois, comme toujours, restez en sécurité, en bonne santé, positifs et créatifs !

// p 30, lignes noires dans l'encart en bas à droite //

**Now we can include more descriptive text and/or a snippet of the
function.
Here is the code that will actually switch the theme to the user selection...**

Maintenant,  vous pouvez ajouter plus de texte descriptif ou un extrait de la fonction.
Voici le code qui va vraiment changé le thème pour celui choisi par l'utilisateur...