Building a Site in Sphinx & reStructuredText¶

Why would anyone want to build a website using Sphinx and reStructuredText? Well, there are some good reasons!

The Bedtime Ramblings Sphinx RST Geek Friendly

Simon Harper

22 Dec 2022

6 min read

Back in the distant past, I built out a WordPress site just for random thoughts, and I pretty much kept it up to date. Skip forward a few years and, thrilled by JAMstack, I moved to a static site generated site using Hugo and the Academic theme. This is a nice system, but after not using it over the covid period, jumping back in was less friendly than you might think.

Now I use Sphinx and reStructuredText (rst) for building documents of all types especially when I need multiple generation endpoints such as HTML, Latex, PDF, ePub etc. So I got to thinking, why not move 100% to this set-up for my website too?

Sphinx is a system set up for data generation, information, manual creation and the like. While currently, the web seems to be focused on shopping, lite (about) information creation, and blogs; indeed my old site was a blog. But is a blog the correct solution with so much focus around dates and times?

In reality, the latest articles are only temporarily useful for the first week or two, then it’s all about the content, information and concepts. And so Sphinx, with a few tweaks, can handle this really well - and in some cases much better than a blog engine.

Tip

So my site is generated with Sphinx to an html endpoint, then checked into git and pushed to github. Github is hooked to a Netlify site. Once pushed the site makes it way to Netlify automatically!

Useful Resources¶

I obviously I was not the first to do or think about this, and it would have been a lot harder if not for the following resources:

Sphinx - https://www.sphinx-doc.org
reStructuredText Cheat Sheet - https://github.com/ralsina/rst-cheatsheet/blob/master/rst-cheatsheet.rst
Sphinx Design - https://sphinx-design.readthedocs.io/en/furo-theme/index.html
Adding tags - https://stackoverflow.com/questions/18146107/how-to-add-blog-style-tags-in-restructuredtext-with-sphinx - not used as I us the index, but interesting pre-processor from Reinout van Rees https://github.com/reinout/reinout.vanrees.org/blob/master/rvo/weblog.py
Sphinx Themes
Creating a Blog on Sphinx Part 1 https://www.errbufferoverfl.me/posts/2020/sphinx-blog-part-one/ Again I didn’t ‘do’ this but it’s useful non the less.
Create bibliographies using sphinxcontrib-bibtex - https://sphinxcontrib-bibtex.readthedocs.io/en/latest/ This is not bad but I also like the more flexible bibtext to html as it adds links for pdfs dois and the like - https://www.lri.fr/~filliatr/bibtex2html/. You will of course need to use pandoc to covert from html to rst; and it costs an extra preprocessing step (you’ll have to work out if it’s important enough to you for this additional step).

Note

Version e973224ab3bcb50cae5e0e2d5f0468f700bf09a0 created on 22/12/2022 @ 15:34. This page is licensed under a Creative Commons Attribution 4.0 International License.