Différences

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

--- issue216:python [2025/04/28 08:15] – d52fr
+++ issue216:python [2025/04/28 18:46] (Version actuelle) – andre_domenech
@@ Ligne 1: / Ligne 1: @@
+**You know what it's like, you're having a party and that one crazy guy shows up, and you're wondering 'who the hell invited this guy?'
-You know what it's like, you're having a party and that one crazy guy shows up, and you're wondering 'who the hell invited this guy?'
 Just kidding. We couldn't have an 18th birthday bash and not invite everyone's favourite crazy Python guy.
@@ Ligne 11: / Ligne 10: @@
 The Trasforiua representative somewhat reminds me of Billy Mumy's character Lennier (a Minbari) from Babylon 5.
-It's amazing to me how Terran Science Fiction got things so right on the appearance of many of the races of the interstellar community.  That having been said, there is a whole lot that they didn’t get right either.
+It's amazing to me how Terran Science Fiction got things so right on the appearance of many of the races of the interstellar community.  That having been said, there is a whole lot that they didn’t get right either.**
-Anyway, Ronnie contacted me about the 18th anniversary issue, so I moved some of my new daily tasks to write another article (something I've been meaning to do for a while).
+Vous savez ce que c'est : vous organisez une fête et un type un peu fou débarque, et vous vous demandez : « Mais qui a bien pu l'inviter ? »
+Je plaisante. Impossible de fêter un 18e anniversaire sans inviter le Python le plus fou de tous.
+Salutations encore, camarades Formes de Vie Sensibles. Ça fait un bail, n'est-ce pas ? Non, je ne suis pas retourné sur Terra. Je suis toujours à la Station Decturienne, à essayer de faire en sorte que ces deux groupes de formes de vie s'entendent bien entre eux et avec le reste de l'univers.
+Le représentant de Gozorn est (à mon avis) un croisement entre La Chose des Quatre Fantastiques et l'être rocheux Yarnek (un Excalbien) de l'épisode 22 de la saison 3 de Star Trek TOS (la série originale), nommé « Le Rideau Sauvage ». Pas aussi sarcastique que l'un ou l'autre, mais tout juste.
+Le représentant de Trasforiua me rappelle un peu Lennier, le personnage de Billy Mumy (un Minbari) dans Babylon 5.
+Je suis stupéfait de voir à quel point la science-fiction terrienne a réussi à bien cerner l'apparence de nombreuses races de la communauté interstellaire. Cela dit, il y a aussi beaucoup de choses qu'ils n'ont pas bien comprises.
+**Anyway, Ronnie contacted me about the 18th anniversary issue, so I moved some of my new daily tasks to write another article (something I've been meaning to do for a while).
 So, HAPPY ANNIVERSARY, FCM!!!!!  I have enjoyed all the years that I’ve been part of it and hope that I will be able to continue writing for it in the future!
@@ Ligne 27: / Ligne 39: @@
 Per the MkDocs GitHub repository (https://github.com/mkdocs/mkdocs),
-“MkDocs is a fast, simple and downright gorgeous static site generator that's geared towards building project documentation. Documentation source files are written in Markdown, and configured with a single YAML configuration file. It is designed to be easy to use and can be extended with third-party themes, plugins, and Markdown extensions.”
+“MkDocs is a fast, simple and downright gorgeous static site generator that's geared towards building project documentation. Documentation source files are written in Markdown, and configured with a single YAML configuration file. It is designed to be easy to use and can be extended with third-party themes, plugins, and Markdown extensions.”**
-So this is a free project designed to help design a project ssg written (mostly) in Python.
+Bref, Ronnie m'a contacté au sujet du numéro du 18e anniversaire, j'ai donc déplacé certaines de mes nouvelles tâches quotidiennes pour rédiger un article de plus (ce que je voulais faire depuis un moment).
+Alors, JOYEUX ANNIVERSAIRE, FCM ! J'ai apprécié toutes ces années passées à y participer et j'espère pouvoir continuer à y écrire à l'avenir !
+Pour ce numéro anniversaire, je parlerai des générateurs de sites statiques, et d'un en particulier, MkDocs.
+Générateurs de sites statiques
+Si vous ne connaissez pas les générateurs de sites statiques (GSS), ils permettent à un programmeur non-HTML de créer un site Web basé sur un modèle (ou un thème) et de l'héberger sur des sites comme GitHub et d'autres. Prenons l'exemple de mon propre site Web. https://thedesignatedgeek@xyz est un site hébergé sur mon dépôt GitHub via leurs pages GitHub. Mon site est basé sur un GSS utilisant Jekyll. Lorsque j'ai créé mon site, le SSG Jekyll était le meilleur que j'ai pu trouver et était initialement une solution rapide pour créer un site Web rapidement. Je ne m'attendais pas à ce qu'il dure près de 8 ans dans sa version actuelle.
+MkDocs est arrivé !
+Selon le dépôt GitHub MkDocs (https://github.com/mkdocs/mkdocs),
+« MkDocs est un générateur de sites statiques rapide, simple et vraiment magnifique, conçu pour la création de documentation de projet. Les fichiers sources de la documentation sont écrits en Markdown et configurés avec un seul fichier YAML de configuration. Il est conçu pour être facile à utiliser et peut être étendu avec des thèmes, des plugins et des extensions Markdown tiers. »
+**So this is a free project designed to help design a project ssg written (mostly) in Python.
 Please notice the part stating that MkDocs is “geared towards building project documentation”.
@@ Ligne 49: / Ligne 78: @@
 mkdocs new my-project
-Now, change to your new project folder.
+Now, change to your new project folder.**
-The mkdocs.yml is the configuration file.  The docs folder holds all the “pages” that make up your site.  The main page has already been started for you.
+Il s'agit d'un projet gratuit conçu pour vous aider à concevoir un projet SSG écrit (principalement) en Python.
+Veuillez noter la partie indiquant que MkDocs est conçu pour la création de documentation de projet.
+Le processus de création de votre site statique est très similaire à celui de Sphinx. Cependant, Sphinx utilise le langage RST pour générer les pages, tandis que MkDocs utilise Markdown.
+Installation
+L'installation est très simple. Utilisez pip pour l'installer. Cependant, je vous suggère (au moins à des fins d'évaluation) de créer un environnement Python virtuel, afin que rien ne modifie votre environnement de travail. Si vous ne vous souvenez plus comment procéder, consultez mon article dans FCM n° 208 d'août 2024.
+Utilisez maintenant pip (pip3) pour l'installer et toutes les autres dépendances.
+pip install mkdocs
+Démarrage
+Une fois cette étape terminée, accédez à votre terminal d'environnement virtuel et saisissez :
+mkdocs new my-project
+Accédez ensuite au dossier de votre nouveau projet.
+**The mkdocs.yml is the configuration file.  The docs folder holds all the “pages” that make up your site.  The main page has already been started for you.
 To see what your “site” will look like, in the terminal type:
@@ Ligne 68: / Ligne 120: @@
   - License: license.md
-theme: readthedocs
+theme: readthedocs**
-You can quickly see that the site_name section relates to the name at the upper left of the screen shot.  The nav: section contains a list of all of the pages you created and want to be seen on your site.  In the example above, there are three pages, the home page, an about page and a license page.  Finally you can see that my test site uses the readthedocs theme, which is built into MkDocs.  There are a number of different themes that are available.
+Le fichier mkdocs.yml est le fichier de configuration. Le dossier docs contient toutes les pages de votre site. La page principale est déjà créée.
-Speaking of themes, the original screenshot is created using the default theme for MkDocs.  Here’s a shot of my dummy site using the readthedocs theme…
+Pour visualiser l'apparence de votre site, saisissez :
+mkdocs serve
+Plusieurs actions se dérouleront alors, toutes affichées sur votre terminal. Lorsque vous verrez « Serving on http://127.0.0.1:8000/ » dans le terminal, ouvrez votre navigateur à l'adresse indiquée et vous verrez apparaître tout votre travail (enfin, celui de l'équipe MkDocs). Vous obtiendrez un résultat similaire à l'image ci-dessus.
+Retournons un instant en arrière et parlons du fichier mkdocs.yml. C'est là que sont stockées toutes les informations de configuration de votre site. Voici un exemple du site de test que j'ai conçu :
+site_name: My Docs
+nav:
+  - Home: index.md
+  - About: about.md
+  - License: license.md
+theme: readthedocs
+**You can quickly see that the site_name section relates to the name at the upper left of the screen shot.  The nav: section contains a list of all of the pages you created and want to be seen on your site.  In the example above, there are three pages, the home page, an about page and a license page.  Finally you can see that my test site uses the readthedocs theme, which is built into MkDocs.  There are a number of different themes that are available.
+Speaking of themes, the original screenshot is created using the default theme for MkDocs.  Here’s a shot of my dummy site using the readthedocs theme…
 You can find information on the two built-in themes at https://www.mkdocs.org/user-guide/choosing-your-theme/ and a list of third party themes at https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes .
@@ Ligne 86: / Ligne 155: @@
 Deploying
-This is the big decision maker, in my mind.  How and where you can put your project documentation can make or break the entire system.  Thankfully, there is a very large section of MkDocs on just this subject.  According to them, you can host your project documentation just about anywhere.  The primary locations would include GitHub, GitLab and ReadTheDocs.org are just three places you can use to host your documentation.  See https://www.mkdocs.org/user-guide/deploying-your-docs/ for more information.
+This is the big decision maker, in my mind.  How and where you can put your project documentation can make or break the entire system.  Thankfully, there is a very large section of MkDocs on just this subject.  According to them, you can host your project documentation just about anywhere.  The primary locations would include GitHub, GitLab and ReadTheDocs.org are just three places you can use to host your documentation.  See https://www.mkdocs.org/user-guide/deploying-your-docs/ for more information.**
-Bottom line
+Vous pouvez rapidement constater que la section « site_name » correspond au nom en haut à gauche de la capture d'écran. La section « nav: » contient la liste de toutes les pages que vous avez créées et que vous souhaitez voir apparaître sur votre site. Dans l'exemple ci-dessus, il y a trois pages : la page d'accueil, une page « À propos » et une page de licence. Enfin, vous pouvez constater que mon site de test utilise le thème readthedocs, intégré à MkDocs. Plusieurs thèmes sont disponibles.
+À propos des thèmes, la capture d'écran originale a été créée avec le thème par défaut de MkDocs. Voici une capture d'écran de mon site factice utilisant le thème readthedocs :
+Vous trouverez des informations sur les deux thèmes intégrés sur https://www.mkdocs.org/user-guide/choosing-your-theme/ et une liste des thèmes tiers sur https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes.
+Prise en charge de Markdown
+Cela peut poser un problème majeur pour certains, compte tenu de la multitude de versions différentes des spécifications Markdown.
+https://markdownguide.offshoot.io/basic-syntax/
+Déploiement
+À mon avis, c'est la décision la plus importante. La manière et l'emplacement de la documentation de votre projet peuvent influencer le succès ou l'échec du système. Heureusement, une section importante de MkDocs est consacrée à ce sujet. Selon eux, vous pouvez héberger la documentation de votre projet pratiquement n'importe où. Parmi les principaux emplacements disponibles, on trouve GitHub, GitLab et ReadTheDocs.org. Consultez https://www.mkdocs.org/user-guide/deploying-your-docs/ pour plus d'informations.
+**Bottom line
 While there are a few small “gotchas” that at first glance look like major roadblocks, the customization capabilities of MkDocs offers, MkDocs seems like a good tool to create your project documentation.  It’s not (in its current configuration) for everyone that might want a Static Site, since there is no current support for blogging, emailing and so on.
@@ Ligne 102: / Ligne 187: @@
 As always; stay safe, healthy, positive, creative and most importantly, believe in miracles!
-Crazy Uncle Greggggie
+Crazy Uncle Greggggie**
+En résumé
+Malgré quelques petits pièges qui, à première vue, semblent être des obstacles majeurs, les possibilités de personnalisation offertes par MkDocs semblent en faire un bon outil pour créer la documentation de votre projet. Dans sa configuration actuelle, il ne convient pas à tous ceux qui souhaitent un site statique, car il n'offre pas de prise en charge pour les blogs, les e-mails, etc.
+Le plus important pour moi est que plus de 80 % du projet est écrit en Python. Une grande partie du projet utilise Python-Markdown (https://python-markdown.github.io/) et de nombreuses extensions et projets tiers (https://github.com/mkdocs/catalog#-theming) sont disponibles pour vous guider si vous souhaitez/devez modifier/personnaliser certains éléments. Sans parler du potentiel d'apprentissage, qui ne se limite pas aux SSG et à Markdown.
+C'est, à mon humble avis, un excellent projet dont tout programmeur Python pourrait tirer de précieuses compétences.
+Conclusion
+Je ne sais pas à quelle fréquence je pourrai vous tenir au courant (vous tous les Texaciens), car il y a un effort important pour installer un nouveau système de communication quantique par intrication (QEComms) ici à Decturian Station.
+Comme toujours ; restez en sécurité, en bonne santé, positifs, créatifs et surtout, croyez aux miracles !
+Oncle Greggggie le fou