How to add blog style tags in reStructuredText with Sphinx

Question

For a programming language documentation project written in reStructuredText and rendered to HTML with Sphinx, I want to group my functions into logical groups like: String (all string functions), Web (all web-related functions), List (anything to do with list handling), etc.. Now, since functions can be members of several groups I want to add tags in some way, just like you would to blog posts.

It would be really neat if there were a Sphinx extension (or way of using Domains for example) to add the tags and then generate a page per tag referencing all those functions, an overview of all tags and a cross-reference at the bottom of each function page. Is this feasible and if so, how?

Example:

substring
=========

**substring (**\ *<string,number>* **text,** *number* **start,** *number* **end*)**

Description
-----------

Returns the substring of string ``text`` 
between integer positions ``start`` and position ``end``.

The first character in the string is numbered 0. 
The last character returned by ``substring`` is the character before position ``end``.
Optionally ``end`` can be left out, which means
the returned string will end at the last position of ``text``.

Example
-------

    Executing the following code:
    
    ::
            
        log(substring("Welcome to our site!", 0, 7));
        log(substring("Welcome to our site!", 0));
        
    will print:
    
    ::
    
        Welcome
        Welcome to our site!

Tags
----

String

Answer 1

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

Answer 2

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