2025-05-30 RSS in Sphinx
========================

.. feed-entry::
   :date: 2025-05-30

:doc:`My notebook (this) <index>` now has `an RSS feed </notebook-feed.xml>`__!

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 <https://stackoverflow.com/a/1588720>`__ which was moderately coupled to his site
- `yasfb <https://github.com/sphinx-contrib/yasfb>`__ which assumed you wanted a feed of all pages, not a subset
- `ABlog <https://ablog.readthedocs.io/en/stable/>`__ which “converts any documentation or personal website project into a full-fledged blog” which is a bit heftier than I wanted

But `sphinxcontrib-newsfeed <https://github.com/prometheusresearch/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 <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-toctree>`__ and I did not fancy maintaining the list by hand.

Then, with fantastic timing (thanks!), `Tony Ruža added glob support <https://github.com/prometheusresearch/sphinxcontrib-newsfeed/pull/4>`__!

A few tweaks later to:

- `Add support for :reversed: in the feed directive <https://github.com/prometheusresearch/sphinxcontrib-newsfeed/commit/840e981ed86bf6216d04bb5b2f63fa24e2eba9d8>`__ so newest globbed items would come first in the feed
- `Fix a check for datetimes without time information <https://github.com/prometheusresearch/sphinxcontrib-newsfeed/commit/3945ce5f91c961e23f88df273ecbe51b77a9e13a>`__ 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 <https://github.com/prometheusresearch/sphinxcontrib-newsfeed/commit/0194b1283ad095b24c15426aa17d6d235114ba38>`__ 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 <https://github.com/doismellburning/sphinxcontrib-newsfeed/tree/feature/my-glob>`__ seems to do the job rather adequately!