Toc/list with all classes generated by automodule in sphinx docs

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)

Seconded, Sphinx even generates permalink anchors at each function/class/method block. See this for a hint on a hand-coded solution: http://stackoverflow.com/questions/7753805/sphinx-automodule-how-to-reference-classes-in-same-module?rq=1 — kitsu.eb, Aug 30 '12 at 20:12

score 2 · Accepted Answer · answered Sep 17 '12 at 13:04

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);
});

});

In the above code, having `
` seems necessary for getting it to display acceptably. I put the container in a file `toc.txt` and "included" it using `.. include:: toc.txt`. — Asclepius, Jul 02 '13 at 20:14
I also added the line `x.push(['Exceptions','dl.exception > dt']);` for `Exception` classes. — Asclepius, Jul 03 '13 at 22:37

score 2 · Answer 2 · answered Sep 11 '18 at 23:15

2

Sphinx now has an autosummary extension that builds summaries and toctrees based on autodoc. This way you just need to insert the following lines into your pymunk.rst:

.. currentmodule:: pymunk

.. autosummary::
   :nosignatures:

   Space
   Circle

answered Sep 11 '18 at 23:15

Caio S. Souza

141
3
11

Toc/list with all classes generated by automodule in sphinx docs

2 Answers2