search

lab-cosmo / chemiscope

An interactive structure/property explorer for materials and molecules
http://chemiscope.org
BSD 3-Clause "New" or "Revised" License
121 stars 29 forks source link

Include chemiscope in docs using sphinx #276

Open ceriottm opened 1 year ago

ceriottm commented 1 year ago

It would be very nice to be able to include "passive" chemiscope viewers into autogenerated documentations, using sphinx or perhaps nbsphinxgallery.

Luthaf commented 1 year ago

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.

ceriottm commented 1 year ago

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.

Luthaf commented 1 year ago

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?

sandipde commented 1 year ago

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.