Surprisingly sphinx does not offer a role to markup other parameters. Using :obj:`...` creates a random, misleading link and ``...`` renders into a completely different format. Therefore I would like to define a custom role arg which I can use like this:
def is_comment(self, ln: str) -> bool:
'''
Check if :arg:`ln` is a comment.
:param ln: The current line
:return: :const:`True` if :arg:`ln` is a comment
'''
I have already figured out that I can define a custom role by setting rst_prolog in docs/source/conf.py (thanks to this answer)
rst_prolog = '''
.. role:: arg
'''
However, I am lost how to define how this role is supposed to be rendered.
It is easy to inherit from a different role like this:
rst_prolog = '''
.. role:: arg(obj)
'''
Which looks good but has the same problem like using obj directly: It creates wrong links.
My second attempt was to not inherit from another role but specify a class as shown here:
rst_prolog = '''
.. role:: arg
:class: code
'''
but that gives several error messages <rst_prolog>:3: WARNING: Explicit markup ends without a blank line; unexpected unindent. Adding an empty line below does not help.
Is there an easy way to make arg(obj) not be a link?
What am I doing wrong in my second attempt?
EDIT: I am one step further. The problem in my second attempt was that I indented :class: code with a tab. Using spaces instead silences the error message but the code is not highlighted.
Right Click > Inspect in Firefox shows that it is correctly translated to
Check if <span class="code">ln</span> is a comment.
However, the code class is ignored.
If I inspect the True (which is rendered as expected) I see that it is using the code class and that the code class is defined in nature.css as
code {
background-color: #ecf0f3;
color: #222;
/* padding: 1px 2px; */
font-size: 1.1em;
font-family: monospace;
}
How do I use the code class?
