Using chemiscope in sphinx documentation generated by `myst-nb`

[awvwgk]

We are trying to use chemiscope for visualization in the documentation of tblite, however the chemiscope javascript component cannot be found. Is there any guidance on how to setup the JS component of chemiscope with sphinx?

Error message in HTML output:

Failed to load view class 'ChemiscopeView' from module 'chemiscope'
Error: Script error for "chemiscope"
http://requirejs.org/docs/errors.html#scripterror
    at makeError (https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.4/require.min.js:1:1067)
    at HTMLScriptElement.onScriptError (https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.4/require.min.js:1:13218)

Error message in browser log:

strict mode: use allowUnionTypes to allow union type keyword at "#/properties/state/additionalProperties/properties/buffers/items/properties/path/items" (strictTypes)
Failed to load resource: the server responded with a status of 404 ()
geometry.html:1  Refused to execute script from 'https://tblite--257.org.readthedocs.build/en/257/tutorial/python/chemiscope.js' because its MIME type ('text/html') is not executable, and strict MIME type checking is enabled.
embed-amd.js:26 Falling back to https://cdn.jsdelivr.net/npm/ for chemiscope@0.8.4
embed-amd.js:16  Error: Script error for "chemiscope"
http://requirejs.org/docs/errors.html#scripterror
    at makeError (require.min.js:1:1067)
    at HTMLScriptElement.onScriptError (require.min.js:1:13218)

Example: https://tblite--257.org.readthedocs.build/en/257/tutorial/python/geometry.html#visualization

[Luthaf]

So this seems to be the core issue: Refused to execute script from 'https://tblite--257.org.readthedocs.build/en/257/tutorial/python/chemiscope.js' because its MIME type ('text/html') is not executable, and strict MIME type checking is enabled.

What webserver are you using for this? Ideally should be configured to properly send the js file with text/javascript MIME

[awvwgk]

The path https://tblite--257.org.readthedocs.build/en/257/tutorial/python/chemiscope.js does not exist, it returns 404. It seems to me that using chemiscope from a notebook translated by sphinx expects the js file in the path, this choice is probably not right. Can I configure this behavior for chemiscope or do I have to upload the chemiscope.js next to all notebooks for this?

[Luthaf]

Ah, sorry I missed that. I see that you are directly including jupyter notebooks in the sphinx documentation; how are you doing this integrations? We are mainly using the sphinx integration through sphinx-gallery ourself, which then uses the .. chemiscope:: <path/to/json> custom sphinx directive.

[awvwgk]

I am using myst-nb to run the notebook and convert it to rst. In principle, I could also add the .. chemiscope:: directive in the notebook, however in this case the notebook would not be able to display the viewer if used as a notebook directly.

[Luthaf]

It looks like there are ways to customize how myst-nb convert data to rst: https://myst-nb.readthedocs.io/en/stable/render/format_code_cells.html#customise-the-render-process. Do you think this is something you could help implementing?

[ceriottm]

@awvwgk did you make any progress with implementing myst-nb output of chemiscope? it shouldn't be too bad, one needs "just" to export the json, copy it over, and inject the custom sphinx directive in the rst.

[awvwgk]

I found that you can register the plugin for rendering in myst_nb output in pyproject.toml with

[project.entry-points."myst_nb.renderers"]
chemiscope = "chemiscope.sphinx.myst_nb:ChemiscopeMimeRenderPlugin"

The plugin itself would be defined via

from myst_nb.core.render import MimeRenderPlugin, NbElementRenderer, MimeData

from chemiscope.sphinx.nodes import chemiscope


class ChemiscopeMimeRenderPlugin(MimeRenderPlugin):
    """
    Custom renderer for Chemiscope MIME type.
    """

    @staticmethod
    def handle_mime(
        renderer: NbElementRenderer,
        data: MimeData,
        inline: int,
    ) -> None | list[nodes.Element]:
         """
         Handle the Chemiscope MIME type.
         """
         if not inline and data.mime_type == "application/vnd.jupyter.widget-view+json":
              # Check if widget is a Chemiscope widget
              ...
              # Turn into docutils node
              node = chemiscope()
              return [
                  node,
              ]
         return None

What is missing right now is how to check the data.content from MimeData for being a chemiscope widget and then reconstructing the docutils node from the widget.