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

Question

每次我都要引用一个方法，我宁愿不引用。:func:`package.subpackage.module.method`特别是对于经常使用的方法。有没有办法以某种方式 "注册" package.subpackage 惟有 module.method 够了吗？(最好是。package.subpackage.module所以 method 就足够了，假设没有冲突）。)

一个解决方案不应该涉及到将目录添加到 package 或 subpackage但我可以把任何东西加到 docs/. 请注意，这里的问题涉及到一个 method 在docstring的模块之外定义的(否则就是 .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` 将被替换为 :role:`spam <foo.bar.baz.spam>`，无论其具体作用如何(class, func, mod，什么的）。) 当然，这只是一个草案，还没有经过测试，但你应该明白这个想法。甚至可以作为一个新的Sphinx扩展项目的良好起点 :-)

Answer 2

从你能看到类、函数或方法的那一刻起，在索引中你就可以省略名称的书写。

:func:`~package.subpackage.module.method`
:meth:`~package.subpackage.module.method`

你可以简单地写。

:func:`.method`
:meth:`.method`

注意 点子的运用 . 是必要的，如果你要交叉引用本地作用域之外的东西。例如，如果你引用的是你写交叉引用的类中的一个属性或方法，那么下面的做法就可以了。

:meth:`method`
:attr:`method`

还请注意，在作用域内 :meth: 和 :func: 都可以互换使用。然而，在范围之外，你必须使用精确的角色，这取决于你是引用一个方法，还是引用一个函数。

请注意，你可以有名称冲突，因为相同的名称可以在不同的模块中用于不同的对象。在这种情况下，你应该使用完全限定的名称来区分你到底引用的是哪个对象。

重要的是要检查索引，以验证对象是否已经被插入其中（这是由你的 .rst 文件）。) 一般的索引会显示 "对象名（完全限定名）"，如果在索引中，那么可以进行交叉引用。

---

编辑：下面是一个显示的变通方法。.method 作为 class.method; 上述信息适用。

`ClassName.`:meth:`.method`