Enable interactive code in the documentation

[nathanshammah]

This could be done with jupyter-book, as discussed in the Mitiq meeting, which extends capabilities of my-binder.

[nathanshammah]

Quick update on the findings so far:

• 1. As expected, setting up My Binder was very straightforward, and Mitiq runs on cloud if you click here ---> , where one can fire up a new notebook and test that Mitiq is installed:

• 2. Right now there are no jupyter notebooks in the documentation to point to, so the user does not see interactive examples. Point 1. was enabled just by copy-pasting the Mitiq repo link in the Mybinder.org website. It may be possible that by adding specifications in an appropriate .yml file in the MItiq Github repository, the My Binder instructions will be such that they include plugins needed to make the .rst, .md, and .myst examples interactive and runnable, such as Myst-NB and jupytext. I am looking into this.
• 3. The alternative approach is to use Jupyter Book (JB), which is great, and I went through the whole online documentation. I particularly like the Thebe options that keeps you in the webpage and make it interactive without changing it at all, and the plotly integrations (maybe plotly is also configurable with jupyter nb). However, there are a couple of points to understand properly and decide upon here. I found already these issues:
• 4. Currently Jupyter Book is not hosted on Read The Docs (RTD), which is where we are hosting the documentation. I understand that RTD is considering integrating it, but for the time being this would mean not having the documentation hosted at mitiq.readthedocs.io (unless there one places a redirecting link or just a disclaimer to the new docs there) and changes also in continuous integration. Jupyter Book would use GitHub Pages for hosting. I actually think that this could be even better, but it is quite a big breaking change, involving also changes on internet traffic, etc.
• 5. Jupyter Book seems to be a very heavily reworked Sphinx specification, but it is not clear how to keep some crucial features of Sphinx, such as the API doc. I am looking into this as it should be possible to keep them, but I have not found anything explicit about it in the couple of examples I've looked at and in the JB documentation. Note that the conf.py file is changed with a config.yaml file. We also have several plugins customizing our API-doc and user guide, such as Napoleon specifics, etc. I think this could be all ported, but right now is a bit of a question mark.
• 6. In general, I found no straightforward guide to switch from a Sphinx project to a JB. It may be also due to the fact that JB was thought mostly for "books", just like Qiskit used it for its book on quantum optics and computing and then has a manual for Qiskit that is separate. We started the issue with the intention of completely migrating the documentation to JB. I also note that one of my early proposals was to have a book on quantum error mitigation with JB, aside the documentation. Indeed, a good part of the User Guide is thought this way. This opens up to the possibility of splitting the Documentation into a guide to quantum error mitigation, and having a documentation on Mitiq, with a leaner user guide and the API doc. This has both pros and cons. The pros, in my opinion, is that, the massage shifts slightly from "come learn how Mitiq works and see how many quantum error mitigation you can implement", to "come learn what error mitigation is and how easy it is to do that with Mitiq". The change is quite subtle, but may be important. In particular, it may help include examples that use also other libraries more explicitly (of course we always use a intermediate representation one now). I think that part of Pennylane success is also driven by this sort of approach with the QML demos. The cons include an atomization of media that may also make maintenance more difficult.

I will work to assess the points above, some that we can discuss at the Meeting meeting (6pm CET Fridays on Unitary Fund Discord, http://discord.unitary.fund/). Personally I would be happy to enable a first interactive option along point 1., with Juptyer notebooks, which should be super light weight, if doable (should only require adapting a specific .yaml file for My Binder), and then look more carefully into JB migration, that requires more work and deliberation and may take a bit of time.

[astrojuanlu]

Hi! Juan Luis from Read the Docs here, @nathanshammah pinged me privately about this issue.

Your analysis of the current status of the ecosystem is very good. There is ongoing work to make Sphinx support .yaml config, one of the difficulties of supporting Jupyter Book natively on Read the Docs sphinx-doc/sphinx#9040 but the conversation has stalled. You can also see some discussions we had at the beginning of the year at jupyter-book/jupyter-book#1091 (comment).

If you want to enable interactive code in a Sphinx project, you might want to have a look at https://sphinx-thebe.readthedocs.io/ which is also developed by the Executable Books Project, but is a conventional Sphinx extension that should work outside of Jupyter Book.

Happy to jump in a call or discuss this further if I can be of help!

[nathanshammah]

Thanks @astrojuanlu, actually this solution of using sphinx-thebe in the current framework, and possibly add My Binder too, looks great to me and a good fix while things may be sorted out between Sphinx, JB & RTD. Thanks for the context.

[astrojuanlu]

Hi folks! Jupyter Book can finally be used on Read the Docs. This functionality hasn't been released yet and we're looking for beta testers, in case you're interested.

See a working example here: https://github.com/astrojuanlu/jupyterbook-on-read-the-docs

which I created following these docs: https://jupyterbook.org/publish/readthedocs.html

Let me know if you have any questions! Happy to jump to a chat.

[nathanshammah]

I am reopening this as given the recent support of RTD of Jupyter book, we could move from Sphinx to Jupyter Book.

[github-actions]

This issue had no activity for 2 months, and will be closed in one week unless there is new activity. Cheers!