Trying Sphinx for Website

As I said in my previous (and initial!) post, I’m not really happy with Hugo for managing my website and blog. It somewhat does the job and allowed me to finally put Camandro.org online. But if I want to change something, I’ll need to dig into awful css and html code. And… OK, I’ll say it: I hate markdown. There, I’ve said it. Hence, I’ve started looking into Sphinx (look! even the name is cooler!).

Not that reStructuredText format is really a lot better than markdown; in fact it may be even more difficult to use initially, to figure out how to do very simple things. For example, the syntax for links is really awkward. Or maybe it’s just that I had never used it before. Anyway, the reality is that Sphinx can be much more useful than Hugo for things other than this website. For example, the Linux kernel documentation is actually generated using Sphinx. So, it’s much more useful for me as a kernel hacker to learn how to use Sphinx than Hugo.

Obviously, moving to a new generator is not solving all my problems – after all I still need to get used to write more and to write more often. Also, I had some fun just to have an initial Sphinx setup. I’ve started by installing Sphinx on my laptop. Then, after some initial experiments with it, I found out about the ablog extension that looked really handy for blogs management. Unfortunately, the OS I’m running on my personal laptop (OpenBSD) doesn’t package ablog so I had to manually download it and tell my conf.py file where to find it so that it could be loaded:

sys.path.append(os.path.abspath('<ablog PATH>'))
sys.path.append(os.path.abspath('<python-feedgen PATH>'))

extensions = [
  'ablog',
  'sphinx.ext.intersphinx',
]

The second append() above is related to python feedgen, a dependency required by ablog to generate RSS feeds. I had to download it too.

Finally, it was simply a matter of playing a bit with the ablog configuration and things started to make sense. The end result: this website! Yeah, probably not the most amazing thing on the web, but it suites my (current) needs. I may keep tweaking it’s configuration parameters once in a while but for now, I’m done with it.

Previous: Initial post and introduction   Next: FreeBSD on my workstation

Comments

Feel free to comment by sending me an email or pinging me at Mastodon.