Sphinx HTML Embedding#

This notebook shows a recommended way to include interactive MolSysViewer views of your molecular systems in Sphinx-based web documentation.

This workflow assumes that the myst-nb package is installed and that the myst_nb extension is enabled in your Sphinx configuration (for example, in conf.py: extensions = [..., "myst_nb"]).

The workflow is as follows:

  1. Export the view to an HTML file, configured exactly as you want it to appear in your documentation.

  2. Create a Jupyter notebook with the story you want to tell, including the usual code to build and show the view of your molecular system.

  3. Hide the output of the cell that calls view.show().

  4. Embed the exported HTML file via an <iframe> and hide the input cell.

  5. Build your documentation with Sphinx and check the result.

Produce the html file#

Let’s export a simple view to an HTML file to show the procedure. You can check the cookbook unit html_export.ipynb for further details about write_html.

import molsysviewer as viewer
from molsysviewer import new_view

view = new_view('1TCD')
view.show()

view.write_html(output_filename='1tcd_view.html', title='1TCD View')

If you are going to include this HTML file in your Sphinx web documentation, it should be placed in a directory defined for this purpose in your documentation tree. We suggest creating the directory docs/_static/views and copying or exporting your files there (for example, docs/_static/views/1tcd_view.html).

By default, the exported view includes the on-canvas MolSysViewer controls (Reset, Fullscreen, background toggle, Spin, Swing). If you prefer a minimal viewer in your documentation, you can call write_html(..., include_controls=False) when generating the HTML.

During the Sphinx build, everything under _static/ is copied to the output _static/ directory, so the file will be available at _static/views/1tcd_view.html in the final HTML site.

Produce a jupyter notebook to include the view#

Write a Jupyter notebook with a story where, at some point, your molecular system is shown as a MolSysViewer view with the method show(). In this example, let’s simulate we are working with the PDB ID 1TCD and recreate a short story:

“It is time now to have a look at the molecular structure deposited in the Protein Data Bank with the ID 1TCD…”

view = new_view('1TCD')
view.show()

“… As you can observe, the molecular system is a homodimer surrounded by several crystallographic water molecules.”

Hide the output of show()#

With the cell where the method view.show() is executed selected in your Jupyter notebook, click on the gear icon (named “Property Inspector”) to open the Common tools that control the behavior of the cell. Add the cell tag remove-output and make sure it is enabled for your view.show() cell.

When Sphinx builds the documentation (with myst_nb), any cell tagged with remove-output will keep its input in the notebook source while hiding the corresponding output in the rendered HTML.

Embed the HTML file with hidden instructions#

The function molsysviewer.thirds.jupyter.load_html_in_notebook embeds the HTML file written for our molecular system as a new cell containing an <iframe>.

To avoid showing this trick publicly in your Sphinx documentation, hide the input code of the cell that calls this function. With the following cell selected, click on the gear icon (“Property Inspector”) to open the Common tools, add the cell tag remove-input, and make sure it is enabled for your load_html_in_notebook cell.

When Sphinx builds the documentation (with myst_nb), any cell tagged with remove-input will keep its output (the embedded iframe) while hiding the corresponding input code block in the rendered HTML.

The relative path used here, ../../../_static/views/1tcd_view.html, is resolved from the location of the final HTML page corresponding to this notebook: it walks up three directories from content/user/examples_and_recipes/ to the documentation root, then points into _static/views/ where the exported HTML file was placed.

Leave a blank cell below the output of load_html_in_notebook so that the embedded view has some visual space and feels more comfortable in the notebook.

Compile your web documentation with sphinx#

Finally, you can run your usual make html command to build your web documentation. Open the generated HTML pages and check that the original show() output has been hidden and replaced by the embedded viewer from load_html_in_notebook.

With this approach, readers only see a clean, interactive MolSysViewer scene, while your notebook keeps the full, reproducible code under the surface.