Migrating the tutorials to JupyterBook

[sserita]

This PR revamps the Jupyter notebook tutorials. Specifically, both doc and jupyter_notebooks have been removed/combined into docs, which can build both the tutorial notebooks and the Sphinx autogenerated documentation.
The relevant section of the README has also been updated and might be useful to those looking through the PR.

Notably, the tutorials are only stored in Markdown format, which is much cleaner for version control (no more run one cell and git "helpfully" tells you you've made changes). The notebooks can be built locally by running jupytext --sync markdown/**/*.md in the docs directory. This will make a parallel file structure in docs/notebooks that is just every file in docs/markdown but as a .ipynb instead. (This can be done for a single specific file as well, but I suspect the blanket statement will be the more common use case).
When we do want to make changes to the tutorials, we can edit the Jupyter notebooks and then sync back the changes to the Markdown using the same command. Git will then pick up the changes which can be committed pushed.

I'm also breaking away from the legacy 0.9.9.* tutorial structure and have attempted to organize the tutorials in a more useful manner. Feedback on the current organization is welcome. Note that all we have to do is rearrange the contents of docs/_toc.yml to reorder how things are rendered - it's completely decoupled from how we actually store the Markdown files (although I've tried to have a similar organization there too).

@coreyostrove: I remember you having to do some fiddling with the Sphinx build to not timeout on ReadTheDocs. We may need to do similar fiddling here - I wanted to wait on testing that until the PR was ready-ish. It was not immediately clear to me how to merge the Sphinx script you had with the JupyterBook build system, but it does wrap Sphinx so in theory most tweaks should be possible?

@kmrudin: I'd like to not wait too long on feedback from collaborators to get this in. Maybe let's say they have until next Friday (10/30) to respond if they want their feedback incorporated here? Of course we can also do minor changes to things later as well.

For the other code owners that were pinged, I've attached the mostly built documentation (with the exception of the autogenerated docs and none of the Jupyter notebooks run). Probably the easiest thing is to open up index.html in a browser and poke around in the tutorials you are roughly responsible for. If everything looks good, great; if not, let me know and we can fix it.

pygsti-docs.zip

[rileyjmurray]

I'm going to leave a bunch of general comments on this file in order to facilitate threaded discussion. There's no significance to the choice of selected lines in these comments.

[rileyjmurray]

See individual comments

[rileyjmurray]

Issue: when I ran jupytext --sync markdown/**/*.md pretty much all .md files changed. Here's a snippet of my terminal

(pgdev311) s1104997ca:docs rjmurr$ jupytext --sync markdown/**/*.md
[jupytext] Reading markdown/examples/1QGST-InterpolatedOps.md in format md
WARNING:root:[jupytext] creating missing directory notebooks/examples/
[jupytext] Updating notebooks/examples/1QGST-InterpolatedOps.ipynb
[jupytext] Updating markdown/examples/1QGST-InterpolatedOps.md
[jupytext] Reading markdown/examples/2QGST-CreatingModels.md in format md
[jupytext] Updating notebooks/examples/2QGST-CreatingModels.ipynb
[jupytext] Updating markdown/examples/2QGST-CreatingModels.md
[jupytext] Reading markdown/examples/2QGST-ErrorBars.md in format md
[jupytext] Updating notebooks/examples/2QGST-ErrorBars.ipynb
[jupytext] Updating markdown/examples/2QGST-ErrorBars.md

Here's my file tree in vscode after running that command.

I've done some looking and I don't think jupytext has an option to turn off this behavior. A hacky fix is to change the recommended build command to

jupytext --sync markdown/**/*.md
git restore markdown/**/*.md

[rileyjmurray]

I have a handful of proposed changes to how Python code blocks are rendered.

Here's a screenshot showing a page with a prominent Python code block.

.

Proposal 1. I'd suggest we add line numbers to code blocks. If they aren't on by default, it would be nice to have the option of toggling them on.

Proposal 2. We should account for the fact that Python code blocks might overflow. One way of doing this is to turn on text wrapping by default. This would be unwise without line numbers. Another mitigation strategy is to make the main <div> of the HTML pages resizable. Right now I can expand the main <div> by collapsing the left sidebar, but (1) I don't think that's very intuitive, and (2) collapsing the left sidebar should be unnecessary when the browser window has plenty of horizontal space.

[rileyjmurray]

Let's add developer notes about how to build the HTML docs from source. It suffices to run

# Executed within pygsti/docs/ 
mkdir _build
# ^ not sure if that's necessary.
jupyter-book build .
# ^ writes to _build by default.