Switching to Sphinx / ReST

Published: November 05, 2020

Updated: November 08, 2020

That's it, I'm tired of WordPress.

There's just too much bloat, too much going on, too many layers of stuff to have the level of control that I want. The interface is clunky and slow and constantly wants me to update a variety of things which are of questionable import to my site anyway. The website itself is slow, and to get it the way I want it I'd have to dig way further into the available themes, or try to build one from scratch.

If I'm going to build it from scratch, why not use a technology that actually interests me?

At my internship at MousePaw Media I recently started using Sphinx and reStructuredText to write documentation files for the project I'm working on. Pretty simple, and pretty cool (although in this case I'm fortunate enough that the web site is all set up - all I have to do is write docs in .rst. So I thought it'd be a good option to try for my personal page, too.

So now I'm researching the best way to go about this. Sphinx, by itself, is designed around building software documentation. That's a little bit different than a blog (although I suppose it doesn't entirely have to be) There are a few decent options for extending Sphinx to a more blog-like setup, though.

Reinout has built some tools to assist Sphinx in converting .rst source files into a blog format, including tagging, and made them public. On the plus side, it's software designed to do basically what I'm thinking of doing. On the down side, there is no quick pip install feature, and it's very specifically designed for Reinout's own website. So, if I want to use that code, I'd have to dig through it and borrow and adapt the pieces I want, while building the rest to my own personal specifications. This might be worth the effort if the other options don't measure up, but isn't a very attractive option to begin with.

Tinkerer is a blogging tool built on Sphinx. It has support for a handful of useful blogging tools, such as Discus, localization, RSS feeds, and more. It does have documentation that should make it fairly straightforward to use. On the down side, it hasn't been updated since 2017. That may not be a problem, as long as it all works fine; I don't need a lot of fancy, new, language features, I just need to generate static HTML from templates plus source files. Definitely an option.

Similarly to Tinkerer, ABlog is built in Python, as an extension for Sphinx, for the purpose of easily converting a project into a fully functional blog. It also supports Discus and RSS feeds if I ever decide to use either of them (which I'm not sure if I will, but it's nice to have options). The tagging and category functions look pretty handy and usable. And it has current development - the last release was just a few days ago.

These all seem like decent tools that do the job they were meant to do. The sites using them are functional. But overall, ABlog seems to have the most (and most recent) documentation and tutorials available. I'm going to start there, get a trial page working, and then migrate my WordPress site over. Next post will probably be about what I have to learn to make that happen...

After sharing this post on dev.to I got a nice comment pointing out some other options I had missed. I didn't go in depth on all of them, but Pelican stood out to me, and ended up being the actual route I am trying first.

This post is tagged: