Set up jupyterhub for alpha-preview

[nathanshammah]

Set up a jupyter hub on UF’s google console. Users will login to their environments.

JupyterLab can be used as start-up environment.

The workshop attendees can find there:

• One master notebook used as an agenda, with links to different material, such as:
• Mitiq html documentation.
• Mitiq source code.
• One mitiq tutorial.

[nathanshammah]

This is done. I set up a jupyterhub with jupyter lab as default framework, updating the hosted version to mitiq v0.1a1 and building the html docs, for all users. This is found in the my_shared_data folder, which is a read only folder, although the users can use the rest of the home path to add notebooks or scripts.

We agreed upon having the getting started from the docs as tutorial. The only problem is that html files do not render well in jupyter notebooks or in jupyter lab. There may be some css information missing or something like that, so that, for example, the rtd_theme we use for the docs does not render, and we see only a bare text html. This can be only partly solved by using, inside a notebook,

from IPython.core.display import display, HTML
display(HTML('guide/guide_02-getting-started.html'))

as this option still can make some visualization issues. Also, links are not clickable within a jupyter notebook. Of course rendering an html should not be a problem on a server, but we interface with it directly through jupyterhub.

My advice is as following:

• copy the Getting Started in the form of a notebook or script.
• add the html docs as zipped file, both online and in an email, so that they can be rendered locally by the workshop users.
  Thanks to @andreamari for help with troubleshooting.

[andreamari]

A simple option to share the html docs, while keeping mitiq private, could be GitHub Pages:
https://help.github.com/en/github/working-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#choosing-a-publishing-source

[nathanshammah]

I like this suggestion, @andreamari. Interested in what @willzeng and @rmlarose think. To avoid issues, I am playing with this feature (publishing a github pages website on a private repo referring to the docs/ folder only) on my private fork, where I removed docs/build from the .gitignore file and pushed the build.

The outcome should be visible at https://nathanshammah.github.io/mitiq/. This is not working right now, even if I chose a Jekyll theme, as suggested on the Github community forum. An open issue seems to pinpoint the incompatibility with sphinx directory choice. The workaround seems to add a mock index.html file in docs/, pointing at the docs/build, and/or change the BUILDDIR in the make file. I am going to give a try to this.

[nathanshammah]

This tweak worked for me. Have a look now: https://nathanshammah.github.io/mitiq.

This is satisfying as it is for me, and closes the issue for me. I'm fine even in letting my personal website link to this in the workshop. And we can tear it down afterwards. I'd need to check that the current master is synced with the alpha-release branch that we have built on the jupyterhub.

By the way: before adding the .nojekyll file, I was getting only the raw html on the github pages website, just as it looked like, @andreamari, on the JupyterLab on our JupyterHub. So I am wondering whether we just need to tweak something similar to a .nojekyll file, or the .gitignore, or something else, also there. In that case we may be able to see the docs from jupyterlab, maybe. But we were still getting some "Forbidden" errors when clicking some of the links, so maybe that's not practical, and this solution is the best.

[nathanshammah]

Have a look at this super lean style: https://nathanshammah.github.io/mitiq/build/html/guide/guide_02-getting-started.html
What do you think? It's very modern and crisp.

[willzeng]

These docs look great @nathanshammah I like that theme a lot