2025-05-30 RSS in Sphinx

Published on 2025-05-30

My notebook (this) now has an RSS feed!

Getting there was a bit of a journey.

There are a number of existing solutions for RSS in Sphinx, but none of them felt quite right:

• Reinout van Rees’s solution which was moderately coupled to his site

• yasfb which assumed you wanted a feed of all pages, not a subset

• ABlog which “converts any documentation or personal website project into a full-fledged blog” which is a bit heftier than I wanted

But sphinxcontrib-newsfeed looked to (mostly) do the job:

• Use a feed directive (similar in style to toctree) to generate an RSS File

• Use feed-entry directives in relevant pages to attach publication date metadata

Unfortunately it didn’t support the toctree glob directive and I did not fancy maintaining the list by hand.

Then, with fantastic timing (thanks!), Tony Ruža added glob support!

A few tweaks later to:

• Add support for :reversed: in the feed directive so newest globbed items would come first in the feed

• Fix a check for datetimes without time information dating back to a small but breaking change in Python 3.5 regarding “zero” times

• Add a “titlesonly” flag to the feed directive to only render titles in output so the Notebook index page wasn’t a (slightly ugly) blog-index style rendering of each item in full, but just a list of titles

and my sphinxcontrib-newsfeed fork seems to do the job rather adequately!