Full Circle Magazine FR

Outils pour utilisateurs

Outils du site

Piste : • finalisation • finalisation • finalisation • finalisation • tutoriel_3 • finalisation • python • python • python • python
issue205: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
issue205:python [2024/06/03 07:10] – d52frissue205:python [2024/06/12 15:27] (Version actuelle) – andre_domenech
Ligne 4: Ligne 4:
  
 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.** 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. **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.
Ligne 12: Ligne 19:
  
 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.** 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
Ligne 30: Ligne 46:
  
 :return: description of the return value** :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. **If there is more than one parameter, simply repeat the param and type keys.
Ligne 44: Ligne 79:
  
 Now we describe the function using the .. py:function:: directive.** 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). **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).
Ligne 60: Ligne 110:
  
 sys.path.append()** 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. **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.
Ligne 72: Ligne 139:
  
 Adding an Autosummary Adding an Autosummary
 +
 You need to create an extra .rst file named something like “api.rst”. In it you place just a few lines…** 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 **API
Ligne 96: Ligne 179:
  
 When you run your next build, you will see the addition to the bottom of the main page…** 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...
  
  
Ligne 105: Ligne 211:
  
 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.** 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 **Conclusion
Ligne 117: Ligne 232:
  
 Until next time, as always; stay safe, healthy, positive and creative!** 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...
 +
issue205/python.1717391421.txt.gz · Dernière modification : 2024/06/03 07:10 de d52fr