Ceci est une ancienne révision du document !
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. Greetings yet again fellow Sentient Lifeforms. It’s been a while, hasn’t it. No, I have not returned to Terra. I’m still out at Decturian Station working to get these two groups of lifeforms to play nice with each other and the rest of the universe. The Gozorn representative is (in my mind) something like a cross between The Thing from Fantastic Four and the rock-like being Yarnek (an Excalbian) from Star Trek TOS (The Original Series) season 3 episode 22 named 'The Savage Curtain'. Not quite as snarky as either, but only just. 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.
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! For this anniversary issue, I’ll be talking about Static Site Generators and one in particular, named MkDocs. Static Site Generators If you are not familiar with Static Site Generators (ssg), they are a way for a non-HTML programmer to create a website based on a template (or theme) and host them on sites like GitHub and others. Take for example my own website. https://thedesignatedgeek@xyz is a site that is hosted on my GitHub repository using their GitHub Pages. My site is based on a ssg using Jekyll. When I set up my site, the Jekyll ssg was the best I could find and started out as a quick answer to getting a website up quickly. I never expected it to last almost 8 years in its current iteration. Enter MkDocs 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.”
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”. The process of creating your Static Site is very similar to using Sphinx. However, Sphinx uses rst language to generate the pages, MkDocs uses markdown. Installation Installation is very simple. You use pip to install it. HOWEVER, I suggest (at least for evaluation purposes) you create a virtual Python environment, just so nothing changes your working environment. If you don’t remember how to do this, please see my article in FCM#208 from August 2024. Now, use pip (pip3) to install it and all the other dependencies. pip install mkdocs Starting Once you have that done, go to your virtual environment terminal and type mkdocs new my-project 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#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: mkdocs serve There will be a number of things that happen at this point, all printed to your terminal. Once you see “Serving on http://127.0.0.1:8000/” in the terminal, you can open your browser to the address shown and you will see all your hard work (well, the MkDocs team’s hard work at this point) you will see something like the image shown above. Let’s step back for a moment and discuss the mkdocs.yml file. This is where you keep all the configuration information for your site. Here’s an example of what the test “site” I designed looks like… site_name: My Docs nav: - Home: index.md - About: about.md - License: license.md 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
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 . Markdown support This can be a very large issue for some, since there are so many different versions of markdown specifications. https://markdownguide.offshoot.io/basic-syntax/ 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.
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. The biggest thing for me is that over 80% of it is written in Python. A very large part of the project uses Python-Markdown ( https://python-markdown.github.io/ ) and there are many extensions and third party projects and extensions ( https://github.com/mkdocs/catalog#-theming ) that you can find to guide you along if there are some things you want/need to change/modify/customize. Not to mention the potential for learning many things, not limited to ssg and markdown. This is, in my humble opinion, a great project that any Python programmer could get some valuable skills from. End Thoughts I’m not sure how often I’ll be able to update you all ( y'all in Texacian ), since there is a major push to install a new QEComms (Quantum Entanglement Communications system) here at Decturian Station. As always; stay safe, healthy, positive, creative and most importantly, believe in miracles! 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