MyST-NB

MyST-NB copied to clipboard

Context

The docs note the latest pattern for glueing objects from other notebooks, which is nice. Currently it seems this only works for text variables. If I do something like:

```{glue:} my_figure
:doc: my_notebook.md
```

Then I get the alt-text of my_figure rather than the image itself. If I try to use the glue:figure directive explicitly, I get:

```{glue:figure} my_figure
:doc: my_notebook.md
```

ERROR: Directive 'glue:figure': Unknown option: doc

So at least the error message is clear. It would be great to be able to glue arbitrary objects across notebooks again.

This is possibly related to #298, though I'm not sure. Please feel free to close if this is a duplicate!

Proposal

Allow glueing of objects defined in other notebooks. IIRC this used to work with older myst-nb versions, but I understand that things have been largely rewritten since 0.13.5.

Tasks and updates

No response

Allow glueing of objects defined in other notebooks. IIRC this used to work with older myst-nb version

Hey @rossbar, well the problem is that it didn't really "work" fully. This is in the sense that, to achieve any glueing between documents, you have to do this in a post-transform, i.e. after all the documents have been initially parsed and cached. Because it is so late in the build events of sphinx (see https://www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx-core-events), it bypasses a number of processing steps (for images) that sphinx would normally have taken care of. So then, we had to "hack" them back in, e.g. here https://github.com/executablebooks/MyST-NB/blob/448d36f483de2bdbf2ac71d8a9b3e8fe75918be7/myst_nb/render_outputs.py#L114-L130

These hacks still did not account for everything, leading to issues like: https://github.com/executablebooks/MyST-NB/issues/354, nor can it account for all sphinx extensions, that do any processing of images, at earlier stages, like say sphinx.ext.imgconverter.

Note, here I am mainly just talking about image processing. If you tried to do anything even more complex, like full markdown rendering, then the problem gets even worse. For "simple" text nodes, this is not so much a problem, since there is not really any additional processing done.

So, hopefully that makes sense (?), why I am hesitant to re-instate such a feature. Unless, of course, someone can come up with a more "robust" way of doing this.

Thanks @chrisjsewell - ~~for the record, the "bug" label was assigned by GitHub, not me :)~~ (turns out there was no bug label :) ) I intend this issue to come off as a feature request rather than a "why doesn't this work anymore" report. I recognize the difficulty of getting everything working within the sphinx framework - I myself failed to figure out how to do so with the old system (see #394).

All that said, the ability to link arbitrary objects (tables, figures, equations, etc.) across documents would be a really nice feature for our use-cases!