Literal text inside role content

[astrojuanlu]

Is it possible to do something like

{py:func}`the Python \`dir\` function <dir>`

?

[agoose77]

@astrojuanlu in theory, Sphinx allows this, and this Python domain role is defined by Sphinx. As such, we should support it too. However, there's always the possibility that it's not been tested yet. I assume you're talking about Jupyter Book and/or the Sphinx Executable Books tools here?

Have you tried it? :)

[astrojuanlu]

Thanks for the prompt reply! The reason I asked is that, when I went to try it, my IDE (VSCode) got really confused:

And indeed, the output gets messed up:

[astrojuanlu]

FTR I'm using Sphinx==6.2.1 with myst-parser==1.0.0

[agoose77]

Ah, I can see there's a nuance that I missed - the literal dir. I believe this is a limitation or ReST / inline roles. Whilst it looks like MyST parses this "wrong", the result would still not work according to this rule.

Pinging @chrisjsewell for his thoughts on the general "should we support this" question.

[rowanc1]

Does it work if you surround with two ` ?

{py:func}``the Python `dir` function <dir>``

(that might just get it past the myst parsing, not the sphinx side though!)

[astrojuanlu]

Fixed the parsing, didn't get me what I wanted 😅