consider jupyter-bookifying recent workshops

[ljwolf]

many of our recent workshops link directly to a github repository where the source for the workshop is stored. However, @thedatalass correctly notes that this is very alienating for many users.

One thing I've looked into is making jupyter-books for workshop content. This has a few advantages.

1. Jupyter book has a content-focused UI, meaning that the intent of the UI is to show you the content of the workshop, not the filestructure of the workshop. This means:
   • inline/rich images in jupyter notebooks
   • navigation hints, like section headings and "next/previous" buttons.
   • appropriate detail/linking back to the source project
2. Jupyter book code can be executed in the browser if the environment is specified, using thebelab (if we figure out the execution environment within which the code executes)

The process involved in making jupyter-books out of our workshops will not be complicated. I propose that we do this at least for the first 5/10 workshops.

[ljwolf]

oh yeah and also this means that every workshop can get hosted at pysal.org. So, for instance, see pysal.org/scipy2019-intermediate-gds

[ljwolf]

To bookify a workshop:

1. follow the jupyter-book directions to set up a jupyterbook in a folder called docs in the root of the workshop.
2. copy the content of the workshop into docs/content.
3. IF you use sections (like we do in github.com/pysal/scipy2019-intermediate-gds,
   • create a directory for each section
   • provide an intro.md file for that section.
4. use the configuration options for the repository settings to serve the website from the /docs folder.

I'm still fuzzy on how to get the thebelab integration working. I've read the directions on integrating with execution contexts, but I'm still fuzzy as to how to get this working. Could ask @choldgraf like we did for the @gdsbook?

[rose-pearson]

Instructions for getting started on windows. If you are on Windows the approach we are using is based on: https://jupyter.org/jupyter-book/intro.html

1. Fork then clone the getting started repo you are going to work on. Repos at: https://pysal.org/getting_started
2. Create a branch called 'gh-pages' (Name is important - needed for github to automatically build the website later)
3. Create a conda environment with Jupyter-book
4. In your cloned repo folder create a demo book (jupyter-book create mybookname --demo)
5. Build this using 'jupyter-book build mybookname/'
6. Add the mybookname subfolder, commit and push
7. Under the Github repository settings scroll down to the 'GitHub pages' section and select the gh-pages branch. The autogenerated website url will appear above. More instructions at the bottom of: https://jupyter.org/jupyter-book/guide/03_build

[ljwolf]

I had been using the docs folder in github.com/pysal/scipy2019-intermediate-gds, but it's OK to serve from the gh-book branch if folks find that easier?

[weikang9009]

Looks amazing!

[choldgraf]

Hey all - this looks awesome :-)

just a quick note that if you try building a jupyter book on windows, please do leave feedback about what is hard/confusing/etc! Getting Ruby to work is a huge pain in the butt in my experience, and we're still trying to figure out the right way to guide people through it (hopefully in the future we can switch to Hugo, and this will make everybody's life much easier)

[sjsrey]

Hey all - this looks awesome :-)

just a quick note that if you try building a jupyter book on windows, please do leave feedback about what is hard/confusing/etc! Getting Ruby to work is a huge pain in the butt in my experience, and we're still trying to figure out the right way to guide people through it (hopefully in the future we can switch to Hugo, and this will make everybody's life much easier)

Hugo all the things ;->

[renanxcortes]

oh yeah and also this means that every workshop can get hosted at pysal.org. So, for instance, see pysal.org/scipy2019-intermediate-gds

This Jupyter book is just amazing!!!

[choldgraf]

Hugo all the things ;->

first I have to learn Hugo (or find someone who knows it) :-)

[darribas]

In case it helps, this is the method we currently use to set up a book:

https://github.com/pysal/notebooks/blob/master/lib/build.py#L77

And below are the ones that build the TOC automatically. To be clear, this is for a very specific structure, but it might be helpful to write a TOC-builder from a more general folder of notebooks maybe?