Helping users build examples from .md source

[jordandsullivan]

Currently, in the landing page for our examples landing page does not list how to run these examples easily (as they are HTML). There's also not very much information about how to generate these notebooks in the docs, except in the Contribution section, and I think this should be accessible to vanilla users as well.

I've thought of a few options to make things easier:

1. Add a button to run the notebook in browser using a tool like google collab or binder.
2. Add a "download as jupyter notebook" button. This one is semi-useful (as long as it also downloads any relevant files that the notebook might use), but doesn't necessarily
3. Add a "download all examples as jupyter notebooks" button. This one is semi-useful (as long as it also downloads any relevant files that the notebook might use), but doesn't necessarily
4. Add a flag for mitiq installation which automatically generates all the jupyter notebooks from the markdown on the user's local machine

[natestemen]

First, 100% agree we need to find an easier way for people to download and use our tutorials on their local machines.

Second, I'll just point out what does exist in this direction. On all the pages of the documentation there is a "show source" link which brings you to a txt file containing the contents of the file you were just on [example for braket tutorial]. The download format of this is MyST markdown, which not everyone will know how to run and will require the downloader to use a tool such as jupytext to convert it to ipynb before running it. This is a pretty painful process which is not documented because it should not be this painful.

Add a "download as jupyter notebook" button

Indeed having a "download jupyter notebook" button has been on our wishlist for quite some time. We included #1619 in unitaryHACK last year, and as you can see from the discussion there, it's not a straightforward feature we can get out of our documentation (or at least it wasn't ~1 year ago).

Add a button to run the notebook in browser

We also used to have some link in Mitiq that linked to mybinder, but they were constantly failing. Check out #1820, and the linked PRs for more info here.

Add a "download all examples as jupyter notebooks" button

What's the use case for someone wanting to do this unless they're going to start doing dev work on Mitiq. What type of user do you think this would benefit?

flag for mitiq installation which automatically generates all the jupyter notebooks

huh that's an interesting idea. Currently the documentation is generally not packaged with the code itself so we would have to do that, and then add a build step for the docs in the wheel or similar. Do you know of any other projects that do something like this? (not a requirement, just curious)

[bdg221]

Do we have any idea how much room it would take up to store the md files as ipynb?

[natestemen]

I don't know the answer to your question, but the amount of memory I don't think is the constraint here. I don't think we should store the ipynb files alongside md file just because why store duplicate data. I do think we will need to build the ipynb files, and then store them in the docs build, however.

[jordandsullivan]

I found a package called Jupyter Book, which seems to do everything we're looking for:

For an example of how this works, take the project https://python.quantecon.org/sir_model.html, which Jupyter-book links from their website as a good example. One of their pages, which contains both markdown and code, looks like this:

At the top righthand corner there are buttons for multiple ways of interacting with the content on that page:

Adopting this would introduce a new dependency, but it seems quite useful. They already have integration with Myst and Jupytext: https://jupyterbook.org/en/stable/file-types/myst-notebooks.html#file-types-myst-notebooks

[bdg221]

This section talks about connecting the page to a github source, launching the notebook in environments like Colab, and other features on that menu. Definitely, looks like it has the functionality we are looking for.

[natestemen]

@nathanshammah has previously done an investigation of Jupyter Book which I would suggest checking out #813 (comment). At the time ReadTheDocs did not support JB, but that has now changed.

There are few things worth checking like does JB have the capability to generate the API-doc, and is it straightforward to switch to? Just wanted to add as more context to the JB discussion.

[nathanshammah]

Thanks @jordandsullivan. Please see these issues for context: #1619 (btw this was a bounty for unitaryhack 2023), and #1517.

[cosenal]

OP's option 2. implemented in #2363. Please take a look.

[natestemen]

Now that 0.37.0 is released and this change will propagate to stable, I'm going to close this!

[cosenal]

Let me leave here a handy VSCode tasks.json that I created to handle .md <> .ipynb conversion

{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "jupytext: MD --> IPYNB",
            "type": "shell",
            "command": "jupytext --to notebook ${file}",
            "group": "build",
            "problemMatcher": [],
            "detail": "Convert Markdown to Jupyter notebook"
        },
        {
            "label": "jupytext: IPYNB --> MD",
            "type": "shell",
            "command": "jupytext ${file} --to myst",
            "group": "build",
            "problemMatcher": [],
            "detail": "Convert Jupyter notebook with Markdown"
        }
    ]
}