Tag: sphinx

I'm a big fan of docs-as-code for more or less any type of content publishing, but I'm less of a fan of Jekyll, the default tool used in GitHub pages. I also prefer ReStructuredText over Markdown as a markup format, so Sphinx is definitely on my shortlist of SSGs (Static Site Generators) for my projects. I recently switched the rst2pdf docs to using Sphinx hosted on GitHub pages, so here are my setup notes.

I've been gushing about docs-as-code, but realised that I haven't shared many hands-on tips for actually building different types of sites in this sort of toolchain. I've been mostly using Sphinx which generates much better-looking documentation than its website suggests. It's a python-based static site generator, with a thriving community …

I'm building a docs-as-code site at work at the moment (you can peek if you like https://developer.aiven.io) and working with ReStructuredText in this setup is new to me. One thing I really missed was the concept of front matter, which I'm not sure is even official or documented but seems to be reasonably widely supported (I promise to save the rant about markdown for another day). It took me a while to figure this out for Sphinx/rst but now I'm looking at it working, I had better write it down before I forget!

As a newcomer to Sphinx, I found many things confusing, but the table of contents or "toc" configuration was the thing that almost made me change my mind and pick a different platform! I now have a setup that works pretty well, using Sphinx External TOC, so I thought I'd share my setup.