我正在记录一组使用 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)
会是最好的,但我不知道它是否在任何地方都可用。
最佳答案
在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 displayget
as the link text.
它适用于 class
、func
、meth
和 attr
,可能还有 any
(我无法让它与 any
一起工作)。
按照模式,试试这个:
:class:`~project1.Class1`
我刚刚在 Pyramid 和 WebOb 中运行了一个测试,这成功了:
:class:`~webob.request.Request`
只有文本 Request
显示并链接到 WebOb API。
关于python - 如何将一个 Sphinx 角色转换为另一个角色?,我们在Stack Overflow上找到一个类似的问题: https://stackoverflow.com/questions/45639845/