How do I convert one Sphinx role to another?
I’m documenting a set of projects that use Sphinx that have benefited greatly from the intersphinx extension. Essentially, there are about 3 utility projects pooled into one larger project, and in the larger project, I need to reference the documentation of the smaller project. I set intersphinx to
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),
}
This allows me to use intersphinx:
:any:`project1. Class1`
It is rendered with the text project1. Link to Class1
. I’d rather it use substandard names, though, so I wrote it at the end
:any:`Class1 <project1. Class1>`
A lot. It’s annoying. I really wanted to set up some characters so I could do it
* :p1:`Class1` is from ``project1``
* :p2:`Class2` is from ``project2``
* :p3:`function1` is from ``project3``
where:p 1:'{text}
‘ is :any:'{text} <project1.{ text}>'
substitution, etc
Is there an easy way to do this? All my searches got very useless information, and the source code of intersphinx is hard to read. Ideally, I could do it somehow
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)
Would be the best, but I don’t know if it’s available anywhere.
Solution
在<a href=”http://www.sphinx-doc.org/en/stable/domains.html?highlight=:py:meth:<code>~Queue.Queue.get</code>#cross-referencing-syntax” rel=” noreferrer noopener nofollow”>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.
It works with class
, func
, meth
, attr
, and possibly any (I can’t get it to work with any
).
Follow the pattern, try this :
:class:`~project1. Class1`
I just ran a test in Pyramid and WebOb and this worked :
:class:`~webob.request.Request`
Only the text Request
is displayed and linked to the WebOb API.