Sphinx引用包含节号和节标题的其他节

Question

我正在使用Sphinx编写一个包含大量引用的文档:

.. _human-factor:

The Human Factor
================

...

(see :ref:`human-factor` for details)

编译后的文档包含以下内容:

(详见人体因素)

相反,我希望它的格式如下:

(详见5.1人为因素)

我试图谷歌解决方案,我发现乳胶hyperref包可以做到这一点,但我不知道如何将其添加到Sphinx构建.

Answer 1

我基本上通过使用这里的 numsec.py 解决了这个问题： https: //github.com/jterrace/sphinxtr

我必须用这个函数替换 doctree_resolved 函数才能获得章节号+标题（例如“5.1 人为因素”）。

def doctree_resolved(app, doctree, docname):
    secnums = app.builder.env.toc_secnumbers
    for node in doctree.traverse(nodes.reference):
        if 'refdocname' in node:
            refdocname = node['refdocname']
            if refdocname in secnums:
                secnum = secnums[refdocname]
                emphnode = node.children[0]
                textnode = emphnode.children[0]

                toclist = app.builder.env.tocs[refdocname]
                anchorname = None
                for refnode in toclist.traverse(nodes.reference):
                    if refnode.astext() == textnode.astext():
                        anchorname = refnode['anchorname']
                if anchorname is None:
                    continue
                linktext = '.'.join(map(str, secnum[anchorname]))
                node.replace(emphnode, nodes.Text(linktext
                    + ' ' + textnode))

为了使其工作，需要在 conf.py 中包含 numsec 扩展，并在 toctree 中添加 :numbered: ，如下所示：

.. toctree::
   :maxdepth: 1
   :numbered: