狮身人面像对包含章节编号和章节标题的其他章节的引用

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 The Human Factor”）。

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 扩展名，并在目录树中添加 :numbered: ，如下所示：

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