How to add blog style tags in reStructuredText with Sphinx

You can make use of indexing feature of sphinx.

ReST:

.. index:: BNF, grammar, syntax, notation

Some rest goes here.

conf.py:

html_use_index = True

I've solved this with some custom preprocessing and a custom directive. My personal website is made with Sphinx, as is my weblog. And a weblog means tags.

First the custom Sphinx directive "tags" that I use like this:

My blog entry header
====================

.. tags:: python, django

Bla bla bla bla

The directive itself translates itself to a bunch of relative links of the form ../../tags/python.html, which works because the blog entries are always in yyyy/mm/dd/ directories.

Second a small preprocessing script that I call from the Sphinx makefile. This script simply generates a tags/TAGNAME.txt file. Sphinx processes it as a regular Sphinx file, so you only have to generate some valid restructured text. For instance:

python
######

.. toctree::
    :maxdepth: 1

    2013-08-23 Praise for github pull requests <../2013/08/23/praise-for-pull-requests.txt>
    2013-08-21 How to say ``[:]`` programmatically in Python <../2013/08/21/programmatical-all-range.txt>
    2013-08-15 Handy tracebacks instead of uninformative segfaults <../2013/08/15/handy-tracebacks-with-faulthandler.txt>

So the core idea is to generate the tag files and re-use as much regular Sphinx behavior as possible. (I use the same approach for index.txt, yyyy/index.txt, yyyy/mm/index.txt and so on).

In case you need some example code: https://github.com/reinout/reinout.vanrees.org/blob/master/rvo/weblog.py