Builder-dependent code

[tuncbkose]

Hi, I've recently ran into a problem with jupyter-book, where I'd like to be able to execute different code based on the builder. To give an example, my use case is that I'm interested in both PDF and HTML outputs, but I want the plots I create to look slightly different in each output.

As described in jupyter-book/jupyter-book#1968, Sphinx's only directive doesn't help with this, but there is some interest in having this functionality. So I ended up hacking something up myself, which ended up being a markdown-it-py plugin.

I was wondering if someone more familiar with the code base could offer some comments towards turning this into a potentially mergeable state. Since getting this to work requires small changes to three different repositories, I'll add a short description here along with a couple of question marks I have in mind.

The biggest question is what kind of a solution to implement. I thought (a new kind of) substitution or a pre-transform only directive were the main mechanisms by which one could try implementing a solution to this problem. By substitution I mean having some sort of marker that is replaced by a code-cell in a builder-dependent manner, where the replacement could be defined in some configuration (like _config.yml for jupyter-book). Pre-transform only could be more flexible, but given that code-cells cannot be embedded in other directives, I thought this avenue may lead to headaches so I didn't explore it.

Another one is where this should be implemented. Looking at the code here and here, I didn't know where would be an obvious place to implement an executable cell specific change, so I implemented on the markdown parsing stage. I'd welcome comments about that as well.

Smaller questions include whether the pre-existing substitution mechanism could be extended instead, notation to be used and other implementation details.

Proposed changes

• Add a builder_name field to MdParserConfig (NbParserConfig in MyST-NB has this, but it seems to be not used much and also not correctly updated when non-HTML builders are used) and a way to update this to the correct value before the parser is used (perhaps here) along with other plugin-specific options (for example a dictionary to pass the replacement code obtained from _config.yml to the plugin).
• Add a markdown-it-py plugin that replaces a given marker containing a key with a code-cell token the content of which depends on which builder is in use.
• Add other code in MyST-Parser and jupyter-book enabling the use of the above extension

Use

In my implementation, I can specify in _config.yml something like

parse:
  myst_builder_dependent_codes:
    key1:
      html: some_code
      latex: some_code
    key2:
...

and then a marker in the source files, such as

{key}

will automatically get replaced with the correct code based on the builder, before the execution step.

Presumably, this can also be removed and the plugin can only add a cell that defines a variable indicating the builder in use, and then users can add their builder-specific code within the files

if JB_SPHINX_BUILDER == 'latex':
    foo()
else:
    bar()

Though this may require implementing this signal for each relevant programming language by the maintainer and thus is a bit less flexible.

I'm happy to share my code but wasn't quite sure how, given it is spread across multiple repositories. Let me know if you have a solution for that.

[tuncbkose]

Pinging @agoose77 because you were involved in the linked issue. Hope the ping is not an inconvenience.