Full Circle Magazine FR

Outils pour utilisateurs

Outils du site

Piste : • labo_linux_1
issue216: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
issue216:python [2025/04/28 09:19] – d52frissue216:python [2025/04/28 18:46] (Version actuelle) – andre_domenech
Ligne 11: Ligne 11:
  
 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.**
 +
 +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.
  
  
Ligne 28: Ligne 40:
  
 “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.”**
 +
 +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. **So this is a free project designed to help design a project ssg written (mostly) in Python.
Ligne 50: Ligne 79:
  
 Now, change to your new project folder.** Now, change to your new project folder.**
 +
 +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.
  
  
Ligne 70: Ligne 121:
  
 theme: readthedocs** theme: readthedocs**
 +
 +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.
 +
 +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
  
  
Ligne 86: Ligne 156:
  
 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.**
 +
 +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 **Bottom line
Ligne 102: Ligne 188:
  
 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
 +
issue216/python.1745824783.txt.gz · Dernière modification : 2025/04/28 09:19 de d52fr