python - 如何将一个 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下:

If you prefix the content with ~, the link text will only be the last component of the target. For example:

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

will refer to Queue.Queue.get but only display get as the link text.

它适用于 class、func、meth 和 attr，可能还有 any(我无法让它与 any 一起工作)。

按照模式，试试这个:

:class:`~project1.Class1`

我刚刚在 Pyramid 和 WebOb 中运行了一个测试，这成功了:

:class:`~webob.request.Request`

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