Toc/list包含sphinx文档中由automodule生成的所有类

Question

我有一个python包即将从epydoc迁移到sphinx.软件包本身记录了sphinx自动模块功能.现在,我希望在我的文档模块的开头,在一个简单的列表/表中对模块中的所有类进行总结,或者在toc-tree中更好(？).

我的自动模块部分(在pymunk.rst中)看起来像

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

然后在pymunk.constraint.rst中

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

等等.在每个文件中,我想要一个所有类的列表,因此很容易得到可用的概述,而无需滚动整个文档或怪异的索引.最终的结果就像

pymunk
    pymunk.Space
    pymunk.Circle
    ...

我的主要目标是构建到html.

现在我正在考虑用javascript做一些聪明的事情来提取并插入一个列表,但是必须有更好的方法吗？

(文档的当前状态:http://pymunk.readthedocs.org/en/latest/pymunk.html)

Answer 1

事实证明，jQuery 是实现此目的的简单方法。

我将其添加到我想要索引的原始第一个文件中：

.. container:: custom-index

    .. raw:: html

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

这样，div 就会被插入到 html 输出中，以便脚本可以放入我想要此索引的所有文件中，并在顶部有一个标题。

然后在 pymunk.js 中我提取了类、函数和数据标签并放入索引中。

使用 javascript 方法解决此问题的缺点是，很难在 TOC 侧边栏中拥有完整的类索引，因为现在它只是从当前页面中选择要包含在索引中的项目。在每个页面加载时创建索引也需要一些工作，也许如果它是一个大模块，那么在某些浏览器中会感觉很慢。

完整js代码如下：

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

});