Steps for custom role in Jupyter Book?

[matthew-brett]

I have a custom role, in fact called data8page, with the usual Sphinx boilerplate, and returning a paragraph node.

It works fine in a tiny sphinx project, producing the rendered paragraph text.

However, when I use it in some Markdown in JupyterBook, the role does not get parsed, so the input text remains unaltered in the rendered source:

{data8page}`foo`

Standard Sphinx roles such as {abbr} and {math} work correctly.

I am importing the role in _config.yml:

sphinx:
  extra_extensions:
    - cfdcode.data8page

in the same form as I'm using in a standalone conf.py for a Sphinx project:

extensions = ['cfdcode.data8page']

Am I doing this correctly? Any ideas how I could debug why it is not being correctly parsed / rendered?

[chrisjsewell]

Heya, so is there then a warning shown that the data8page role does not exist?

[matthew-brett]

There's nothing in the stdout / stderr from jupyter-book build . about data8page. Should I be looking somewhere else?

[choldgraf]

that's weird...if you put an error in the role code does anything happen?

[matthew-brett]

Ah - sorry - I should have said. If I put 1 / 0 into the role function, then no, it does not error, so the role function is not being called. I do get an error from the setup function, that initializes the role, when I put 1 / 0 into that.

[choldgraf]

can you provide a minimum book repo that recreates the problem? It's weird that the setup function is called but the role code isn't being called!

[matthew-brett]

It is weird!

Here's the repo - see the README for instructions : https://github.com/matthew-brett/jbtest

[choldgraf]

So, I think this might be a myst parser thing as opposed to a jupyter book thing.

In your mini Sphinx site, if I activate myst_parser and add a markdown file with this content:

{math}`a = b + c`

{data8page}`some text`

{blah}`foo`

then I see this output:

The rST, this:

:math:`a = b + c`

:data8page:`some text`

:blah:`foo`

yields this:

Note that none of this is jupyter book, just raw sphinx, and note that the data8page role is being treated differently from an unregistered role, it is just not putting out the right output

[matthew-brett]

Interesting.

I see that, in this repo, if I put at 1 / 0 error in the role function, it does error in the Jupyter Book build, so I guess it is being called. I was pretty sure I'd checked that thoroughly before, maybe I was wrong, or was decieved by caching.

[choldgraf]

further sleuthing that I suspect @chrisjsewell has figured out as well (see below)

if I do:

def setup(app):
    # Add runrole roles
    app.add_role('datapage', data8pagerole)
    app.add_role('data8page', data8pagerole)

and add this to a page

{data8page}`some text`

{datapage}`some text`

then the datapage one shows up as expected and the data8page does not. So I suspect that this is something about there being a number in your role name.

I further suspect this because I see @chrisjsewell just opened up executablebooks/markdown-it-py#34 which adds numbers to the regex in the role search :-)

[chrisjsewell]

your sleuthing knows no limits 🧐 but yeh I beat you to it by a couple of hours lol

[choldgraf]

haha

Chris H: discover a problem and then pedantically tell people about it
Chris S: discover a problem and actually fix it

😅

[chrisjsewell]

I'm just playing around with some other bits, then I'll merge and release soon

[westurner]

"How to use roles and directives" executablebooks/MyST-NB#239

• Show examples of how to use roles and directives (with arguments)