Python – How do I convert one Sphinx role to another?

How do I convert one Sphinx role to another?… here is a solution to the problem.

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 display get 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.

Related Problems and Solutions