如何将对象添加到Sphinx的全局索引，或通过别名交叉引用？

Question

每次我都必须引用一个我不愿意引用的方法:func:`package.subpackage.module.method`，尤其是那些经常使用的方法。有没有办法以某种方式“注册”，package.subpackage这样就module.method足够了？（更好的是，假设没有冲突，package.subpackage.module这样就足够了）。method

解决方案不应涉及将目录添加到packageor subpackage，但我可以将任何内容添加到docs/. 请注意，这里的问题涉及method文档字符串模块外部的定义（否则.method有效）。

Answer 1

您可以添加一个简单的扩展来解析您定义的别名。下面的示例是一个简短的概念证明：

# add this to conf.py

from sphinx.addnodes import pending_xref
from sphinx.ext.intersphinx import missing_reference
from docutils.nodes import Text

# alias ref is mapped to a pair (real ref, text to render)
reftarget_aliases = {
    'foo.spam': ('foo.bar.baz.spam', 'spam'),
}


def resolve_intersphinx_aliases(app, env, node, contnode):
    alias = node.get('reftarget', None)
    if alias is not None and alias in reftarget_aliases:
        real_ref, text_to_render = reftarget_aliases[alias]
        # this will resolve the ref
        node['reftarget'] = real_ref

        # this will rewrite the rendered text:
        # find the text node child
        text_node = next(iter(contnode.traverse(lambda n: n.tagname == '#text')))
        # remove the old text node, add new text node with custom text
        text_node.parent.replace(text_node, Text(text_to_render, ''))

        # delegate all the rest of dull work to intersphinx
        return missing_reference(app, env, node, contnode)


def resolve_internal_aliases(app, doctree):
    pending_xrefs = doctree.traverse(condition=pending_xref)
    for node in pending_xrefs:
        alias = node.get('reftarget', None)
        if alias is not None and alias in reftarget_aliases:
            real_ref, text_to_render = reftarget_aliases[alias]
            # this will resolve the ref
            node['reftarget'] = real_ref

            # this will rewrite the rendered text:
            # find the text node child
            text_node = next(iter(node.traverse(lambda n: n.tagname == '#text')))
            # remove the old text node, add new text node with custom text
            text_node.parent.replace(text_node, Text(text_to_render, ''))


def setup(app):
    app.connect('doctree-read', resolve_internal_aliases)
    app.connect('missing-reference', resolve_intersphinx_aliases)

现在，无论确切的角色如何（、、、等等），所有引用都:role:`foo.spam`将替换为。当然，这只是一个草案，未经测试，但您应该明白了。甚至可能是新的 Sphinx 扩展项目的一个很好的起点:-):role:`spam <foo.bar.baz.spam>`classfuncmod