Help with custom renderer

[jonathan-taylor]

I'd like to make a custom renderer that treats some code cells with specific tags different than a usual code cell, i.e. treats its outputs differently in the render process.

It seems like extending CellOutputRendererBaseABC should do it (which I can probably figure out how to do). My question is mostly how to insert such a custom renderer in the entry_points()['myst_nb.mime_render'] group -- tried looking around for other related entry point manipulation example but could not find one...

[chrisjsewell]

Yeh you need to create a small python package, that you can pip install into the environment, that includes a myst_nb.mime_render entry point.
Probably the easiest way to create a minimal python package is with https://flit.readthedocs.io, with an entry point in pyproject.toml like https://flit.readthedocs.io/en/latest/pyproject_toml.html#entry-points-sections:

[tool.flit.entrypoints."myst_nb.mime_reneder`"]
myrenderer = "mypackage:MyRenderClass"

[jonathan-taylor]

Yes, certainly. I guess my use case here is I really want to just render some entire code cells completely differently based on a tag. It's conceivable I'd want to do this for more than one jupyterbook and, yes, I could make separate package for that.

On related note, I have found myself able to modify the output rendering process as desired but I realize now that if I want to modify the entire cell I guess I would have to also replace myst_nb.parser.SphinxNBRenderer specifically its render_nb_code_cell method. I don't see a similar entry_points based way to replace that class.

For a one-off I can of course just fork myst_nb and carry on, but I wonder why the level of customization is just at output rendering rather than whole cell rendering. (I sort of imagined I would be able to customize how an entire cell is handled when reading the docs).

[choldgraf]

Can you describe your use case a bit more? What are you trying to do and why would you like to define a custom rendering process for a single type of cell?

[jonathan-taylor]

It is a bit hacky, I admit, but I want fairly fine-grained control the LaTeX output appearance of an entire cell (OK, many cells) based on some tags. It is likely not a common use case but is part of writing a regular book, not a jupyterbook. But I am going to produce jupyterbooks out of part of this LaTeX project so I'd like to stay as close to .ipynb as possible.

I want control over the LaTeX so it is more humanly readable for final corrections and to perhaps keep e.g. only lines :10 and -5: of stdout. I have spent some time getting something to work in sphinx but it was a bit clunky to edit rst etc. I also wanted to use glue

I realized that myst_nb could likely do the trick if I had this control over the render process. For this case, I think I can just overwrite a bit of SphinxNBRenderer and CellInputNode.

But, I imagined that if someone wants to customize the rendering of the output of some cells, say, based on their own tags, they might also like a reference to the entire cell (for instance to find execution_count). As written it seems like SphinxNBRenderer separates inputs and outputs from that point onward, making customization of the output process having no reference to the related inputs...

[jonathan-taylor]

Guess I should take the thumbs up to mean I might as well just modify SphinxNBRenderer and CellInputNode for this (likely) limited use case. Which is a perfectly good answer.

More generally, I guess myst_nb is not imagining users will want to write custom tags to handle code cells. It seems the existing tags "remove_input"/"remove_output" act only on the inputs or outputs of a cell while in the notebook, the tag lives at the cell level. So I kind of feel like it might be nice to have an interface that allows you to tag a cell and create your own sphinx nodes.

A related use case might be something like nbplots which has tags / options that handle the input of a cell based on some light markup in the cell (e.g. the .. part separator and render_parts options). If I could treat a tagged cell however I want, I could implement this as a version of a tagged code_cell. This may or may not be desirable of course -- just an example of .ipynb related tools that modify a cell's input and output in a given render process.

[jonathan-taylor]

Last comment for tonight -- while I know one can use a {nbplots} ... directive in myst:md this would not be represented as a code cell in a synced .ipynb with myst -- it would show up as part of a markdown cell. BUT, I feel this really is a code cell in spirit, it is just that when rendering this "code cell" the nbplot directive wants customizable behavior.

If it were represnted as a code cell in .ipynb then this would open up the very appealing possibility of editing, running and futzing around with this code cell in a live notebook with the ability to have jupytext directly sync it to md:myst and other good things.