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是一种简单的方法。

我将此添加到我想要索引的原始rst文件中：

.. container:: custom-index

    .. raw:: html

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

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

然后在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);
});

});

Answer 2

Sphinx现在具有一个autosummary extension，可基于autodoc构建摘要和toctree。这样，您只需要在pymunk.rst中插入以下行即可：

.. currentmodule:: pymunk

.. autosummary::
   :nosignatures:

   Space
   Circle

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

2 个答案: