Sphinx & Pygments integration for ANSI rendering

[kdeldycke]

Browsing the list of supported extensions by Shibuya, I realized nbsphinx supports ANSI rendering of code cells.

Looking at nbsphinx's code, it seems that this feature rely on the ansi2html directive, but I can't trace it back to its implementation. Is it a Jinja macro? Or a Sphinx specific tag? Or an rST/Latex workaround?

Anyway, just wanted to point out that nbsphinx ANSI support is reminding me of a similar issue I had to solve to render ANSI codes in Sphinx. So I implemented a collection of ANSI-capable lexers for Pygments, and integrated them into Sphinx.

I just wanted to point to my project as maybe it can be somehow reused/integrated/inspiring for nbsphinx to have better support for ANSI.

Note that my Sphinx extensions plays nicely with Sphinx as demonstrated by its native support in Shibuya.

Also of note is @lepture 's Pygments Styles project, that is brindging the gap between Pygments and Sphinx for styles support.

Relates to:

• Handie ANSI escape sequences in output cells #261
• [BUG]: Jupyter help magic unconverted unicode character #330
• Check for ANSI colors in all plain text outputs #348
• Check for ANSI colors in all plain text outputs #351

[mgeier]

Looking at nbsphinx's code, it seems that this feature rely on the ansi2html directive, but I can't trace it back to its implementation. Is it a Jinja macro?

It is a Jinja filter that's defined in nbconvert: https://github.com/jupyter/nbconvert/blob/216550b2aae4c329f4dab597a96ae7cac30de79a/nbconvert/filters/ansi.py#L47-L71

I implemented/updated most of nbconvert's ANSI color handling (a long time ago):
jupyter/nbconvert#225
jupyter/nbconvert#259
jupyter/nbconvert#696

I also did a similar thing to the classic Jupyter notebook:
jupyter/notebook#1230
jupyter/notebook#2967

And the same thing in JupyterLab:
jupyterlab/jupyterlab#5336
jupyterlab/jupyterlab#5623

Or a Sphinx specific tag? Or an rST/Latex workaround?

It has nothing to do with Sphinx or rST, it directly generates HTML and LaTeX.

I just wanted to point to my project as maybe it can be somehow reused/integrated/inspiring for nbsphinx to have better support for ANSI.

What do you mean by "better support"?

Please provide some examples that your project does "better" than nbsphinx/nbconvert/JupyterLab.

This is my test case for ANSI formatting: https://nbsphinx.readthedocs.io/en/0.9.7/code-cells.html#ANSI-Colors. Feel free to open a PR that adds some examples that don't work well, then we can discuss how to improve them!

[kdeldycke]

Thanks @mgeier for all the pointers and I apologize for the unsolicited advice.

Because I had a hard time digging deeper and couldn't make sense of the call chain, I was under the false impression that ANSI support by nbsphinx was somewhat incomplete. Compound that with the pain I went through to have ANSI being rendered with Pygments within Sphinx, I was simply trying to check if my efforts could be reused somehow.

Again, sorry for the issue. Let's close it while I'm figuring out all the moving parts. I'll be back with more actionable stuff later if I need to.