chemiscope
chemiscope copied to clipboard
lab-cosmo
Include chemiscope in docs using sphinx
It would be very nice to be able to include "passive" chemiscope viewers into autogenerated documentations, using sphinx or perhaps nbsphinxgallery.
I think that the best way to do this will depend a lot on what users are already using for their docs.
For pure sphinx, we could provide a small sphinx extension that would look like this:
.. chemiscope:: ../path/to/data.chemiscope.json
For nbsphinx, it should work with the usual jupyter tools. If it does not for in the current state, there might be some way to configure it.
For sphinx-gallery, I have no idea how to configure the display of the output, I'll have to look how they handle matplotlib and if it can be extended.
Regardless of the solution, chemiscope javascript and JSON can be quite large, and not all viewers of the doc have a very large bandwidth. Because of that, it could be interesting to generate a link to chemiscope.org (maybe with some image of the chemiscope view) and only include image and link in the documentation.
I think that generating a static image is the best way to proceed, if it's easy to do. The level of interactivity of the embedded ipywidgets is very limited in all cases because you can't really use the evenfullness outside individual widgets.
The sphinx-gallery seems to be the easiest one to fix: we mainly need to add a __repr_html__ function to ChemiscopeWidget and friends,
https://github.com/lab-cosmo/chemiscope/blob/9b5c9b12b1b005a599488bf867a69d02f8c823e0/python/chemiscope/jupyter.py#L60
containing the same kind of HTML as the one we are using from the JS side, plus the JSON data.
https://github.com/lab-cosmo/chemiscope/blob/9b5c9b12b1b005a599488bf867a69d02f8c823e0/python/jupyter/src/widget.ts#L108-L134
The remaining question is how to insert the chemiscope javascript in there. We could load it from https://chemiscope.org, or one of the CDN based on top of npm?
This would be very useful. Not sure if you already know this ..ngl viewers are possible to be included in the sphinxdoc directly from.notebook render without any additional steps.
