XD blog

blog page

generator, python, sphinx


2015-04-06 Blog generator

I publish my teaching material as python module. I added some tricks to made that happen. Recently, I was wondering how to add some kind of blog posts inside the documentation. As I have several teaching going on, I did not want to merge all blog posts into a single one where students would have to filter out what blog post is meant for them. So I thought about using a kind of blog generator written in Python on the top of Sphinx. I went through that blog post What's the best available static blog/website generator in Python? which gives a short list of them. It is possible to check their popularity by looking at Top Open-Source Static Site Generators.

I wanted to follow the same design for my blog, same pattern. So I was looking for a tool generated RST files and not directly HTML. Tinkerer seemed a good choice. Should I have to add the message powered by Tinkerer as every site using it is displaying that sentance? I also looked into Pelican, nykola. I also found a very simple one with a French name: éClaircie.

I finally decided to write some code to process my own blog posts and to insert them in the documentation of a an existing python module. It is not finalized yet but it looks like that: An example of a blog post included in the documentation. This process forces me to dig into sphinx devext API which I do not fully understand yet. It is quite difficult to find good examples on the web. What I have implemented is available here: pyquickhelper.helpgen.

By implementing my own blog, I cannot have all the features the static generators have (good templating, many languages). I spent most of my time in implementing the blog post aggregations (categories, months) and the splitting (not more than 10 blog posts per pages). But now, if I want to customize Sphinx a little bit, it is easier.


<-- -->

Xavier Dupré