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.
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.”
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.
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
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.
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