如何将一个 Sphinx 角色转换为另一个角色？

Question

我正在记录一组使用 Sphinx 的项目，这些项目从 intersphinx 扩展中受益匪浅。从本质上讲，大约有 3 个实用程序项目可以输入一个较大的项目，在较大的项目中，我需要参考较小项目的文档。我已将 intersphinx 设置为

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.intersphinx',
    ...
]

intersphinx_mapping = {
    'project1': ('http://internal.url/to/project1/latest', None),
    'project2': ('http://internal.url/to/project2/latest', None),
    'project3': ('http://internal.url/to/project3/latest', None),
}

这让我可以正常使用 intersphinx：

:any:`project1.Class1`

它被呈现为带有文本project1.Class1 的链接。不过，我宁愿它使用不合格的名称，所以我最终写了

:any:`Class1 <project1.Class1>`

一个很多。这很烦人。我真的很想设置一些角色，这样我就可以做到

* :p1:`Class1` is from ``project1``
* :p2:`Class2` is from ``project2``
* :p3:`function1` is from ``project3``

其中:p1:`{text}` 替换为:any:`{text} <project1.{text}>` 等。

有没有简单的方法来做到这一点？我所有的搜索都提供了非常无用的信息，而且 intersphinx 的源代码很难阅读。理想情况下，我有办法去做

def p1_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
    return sphinx.some_module.parse(':any:`{0} <project1.{0}>`'.format(text))

def setup(app):
    app.add_role('p1', p1_role)

会是最好的，但我不知道是否可以在任何地方使用。

Answer 1

third bullet point of Cross-referencing syntax下：

如果您在内容前加上~，则链接文本将只是目标的最后一个组成部分。例如：

:py:meth:`~Queue.Queue.get`

将引用Queue.Queue.get，但仅将get 显示为链接文本。

它适用于 class、func、meth 和 attr，可能还有 any（我无法让它适用于 any）。

按照模式，试试这个：

:class:`~project1.Class1`

我刚刚在 Pyramid 和 WebOb 中运行了一个测试，这很有效：

:class:`~webob.request.Request`

仅显示文本 Request 并链接到 WebOb API。