6

我有一个 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）

4

2 回答 2

2

jQuery 被证明是做到这一点的简单方法。

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

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

});
于 2012-09-17T13:04:13.557 回答
2

Sphinx 现在有一个自动摘要扩展，它基于 autodoc 构建摘要和目录树。这样，您只需将以下行插入您的pymunk.rst:

.. currentmodule:: pymunk

.. autosummary::
   :nosignatures:

   Space
   Circle
于 2018-09-11T23:15:39.287 回答