Question

I have a python package Im about to migrate over to sphinx from epydoc. The package itself is documented with the sphinx automodule function. Now I would like to have a summary of all the classes in my module in a simple list/table in the beginning of my documented module, or even better(?) in the toc-tree.

My automodule part (in pymunk.rst) looks like

.. automodule:: pymunk
    :members:
    :undoc-members:
    :show-inheritance:
    :inherited-members:

then in pymunk.constraint.rst

.. automodule:: pymunk.constraint
    :members:
    :undoc-members:
    :show-inheritance:
    :inherited-members:

and so on. In each file I would like a list of all the classes so its easy to get an overview of whats available without scrolling through the whole documentation or the monstrous index. End result something like

pymunk
    pymunk.Space
    pymunk.Circle
    ...

My main target is to build to html.

Right now Im thinking about doing something clever with javascript to extract out and insert a list, but there must be a better way?

(The current state of the documentation: http://pymunk.readthedocs.org/en/latest/pymunk.html)

Answer 1

jQuery turned out to be the easy way to do this.

I added this to the raw rst file where I wanted the index:

.. container:: custom-index

    .. raw:: html

        <script type="text/javascript" src='_static/pymunk.js'></script> 

This way a div is inserted into the html output so that the script can be put in all files where I wanted this index and have a header on top.

Then in pymunk.js I extracted the class, function and data tags and put into the index.

The downside with a javascript approach to this problem is that it would be hard to have a complete class index in the TOC sidebar as now it just picks the items to be included in the index from the current page. It is also a bit of work to create the index on each page load, maybe if its a big module it will feel slow in some browsers.

Full js code below:

$(function (){
var createList = function(selector){

    var ul = $('<ul>');
    var selected = $(selector);

    if (selected.length === 0){
        return;
    }

    selected.clone().each(function (i,e){

        var p = $(e).children('.descclassname');
        var n = $(e).children('.descname');
        var l = $(e).children('.headerlink');

        var a = $('<a>');
        a.attr('href',l.attr('href')).attr('title', 'Link to this definition');

        a.append(p).append(n);

        var entry = $('<li>').append(a);
        ul.append(entry);
    });
    return ul;
}


var c = $('<div style="float:left; min-width: 300px;">');

var ul0 = c.clone().append($('.submodule-index'))

customIndex = $('.custom-index');
customIndex.empty();
customIndex.append(ul0);

var x = [];
x.push(['Classes','dl.class > dt']);
x.push(['Functions','dl.function > dt']);
x.push(['Variables','dl.data > dt']);

x.forEach(function (e){
    var l = createList(e[1]);
    if (l) {        
        var ul = c.clone()
            .append('<p class="rubric">'+e[0]+'</p>')
            .append(l);
    }
    customIndex.append(ul);
});

});