Rendering as html the nglview.NGLWidget objects in the documentation

[dprada]

While we are documenting MolSysMT, we have come up with a solution to offer NGLView views interactively. @Daniel-Ibarrola, it would be great if you could do the same for the documentation of OpenPharmacophore.

First, look at the main page of MolSysMT docs. As you can see... you can play with the molecule, it is not a static image. Apparently, NGLView is offering an interactive output... but it is not. We have embedded an HTML segment of code with the widget output. How? NGLView can write the output as an HTML file. Let's illustrate the procedure with a simple example:

import nglview as nv
view = nv.demo()
view

Choose the suitable view angle and position by hand and:

nv.write_html('demo.html', view)

You can already open the file 'demo.html' with your web browser and voilà! The web browser shows the interactive representation of the nglview.NGLWidget object. Now... second part of the approach: how can we include this in our documentation? Check the next strategy you can see already in MolSysMT:

• Put your HTML files in the static directory declared in sphinx.
• Trigger the creation of an environment variable with the documentation compilation process to let the function openpharmacophore.view know that an HTML code has to be returned (not the nglview.NGLWidget object).
• Add a new cell in the doc notebook before openpharmacophore.view is invoked to save the path to the HTML file in a variable X. This cell will be hidden with the cell tag 'remove-input'.
• Add to the openpharmacophore.view function the following algorithm:
  • In case the environment variable exists, check if there is a variable X defined in the stack where the function is invoked:
    • If False, return an nglview.NGLWidget normally.
    • If True, return an IFrame from IPython.display (see the above example).

from IPython.display import IFrame

def load_html_in_jupyter_notebook(filename):

    return IFrame(src=filename, width='100%', height='320vh')

As I said, this strategy was already implemented in MolSysMT. Although probably not in its final version, you can check it. See these documents:

• The sphinx makefile
• The molsysmt config file
• The function view
• A notebook in the documentation with an example

A view with different frames can also be written in an HTML file. See for instance this case in MolSysMT doc.

Do you think an approach like this one can be implemented in OpenPharmacophore? Of course, we know that you will give your personal touch to the code. Don't need to copy-paste what we have in MolSysMT. Feel free to find a better solution.

[Daniel-Ibarrola]

Great idea, I'll work on this. The documentation also needs to be updated

[dprada]

To write MolSysMT's documentation we are working with the following sphinx extensions:

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.autosummary',
    'sphinx.ext.intersphinx',
    'sphinx.ext.mathjax',
    'sphinx.ext.todo',
    'sphinx.ext.ifconfig',
    'sphinx.ext.viewcode',
    'sphinx.ext.napoleon',
    'sphinx.ext.githubpages',
    'sphinxcontrib.bibtex',
    'sphinx.ext.extlinks',
    'sphinx_remove_toctrees',
    'sphinx_copybutton',
    'myst_nb'
]

(We are not sure if 'sphinxcontrib.bibtex' is unnecessary once we are already using 'myst_nb'... or maybe it is a required extension to work with bibliography bibtex files. We have to check it)

I would suggest having a look at MyST:

• MyST - Markedly Structured Text - Parser
• MyST-NB

I have the impression that the compilation takes way longer, but it is worth it.

Note about MyST coming from one of the above web pages: MyST-NB is a module within the Executable Books Project, an international collaboration to build open-source tools that facilitate publishing computational narratives using the Jupyter ecosystem. It is also a core component of Jupyter Book.