Suggestion: Move labs to Jupyter Book format

[rickecon]

Suggestion for @jhumpherys @tylerjarvis. I wanted to make a suggestion for the labs that would really give them more legs and accessibility. The Jupyter people have now come up with a format (Jupyter Book) that really marries the PDF concept with the html concept with the executable code concept in a way that can be version controlled. Here is the workflow.

1. Write content as markdown file (.md) along with some Jupyter configuration files and version control those in a GitHub repository.
2. Jupyter book sofware allows you to compile an html version of the book locally (for testing)
3. Set up GitHub Action on book source repository to push changes to a GitHub Pages site of the book upon commits to master.
4. The html site for the Jupyter Book labs would be very accessible, LaTeX- and BibTex-like links and math rendering, and with a click of a button, the page will open as a local Jupyter notebook or Jupyter Lab hosted notebook or a CoLab hosted notebook with executable code and with a specified code environment.

I think this is the sweet spot. We've moved all the documentation for a number of our open source projects over to Jupyter Books. The two following examples are still under development, but they are far enough along to show a lot of the functionality of the medium.

• The Tax-Calculator project's documentation is shown in the associated GitHub page in the upper-right corner. All the source code for that documentation is version controlled in the Tax-Calculator/docs/ folder. Whenever a pull-request is merged that has commits to the files in that folder, a GitHub Action deploys the updated version of the documentation to the GitHub page.
• Another example is the OG-USA model. The Jupyter Book documentation is at the GitHub page associated with the repo, and the source for the documentation is in the OG-USA/docs/ folder.

[jhumpherys]

This is a great idea Rick. We should do it.

…

On Sun, Aug 23, 2020 at 11:52 AM Richard Evans ***@***.***> wrote: Suggestion for @jhumpherys <https://github.com/jhumpherys> @tylerjarvis <https://github.com/tylerjarvis>. I wanted to make a suggestion for the labs that would really give them more legs and accessibility. The Jupyter people have now come up with a format (Jupyter Book <https://jupyterbook.org/>) that really marries the PDF concept with the html concept with the executable code concept in a way that can be version controlled. Here is the workflow. 1. Write content as markdown file (.md) along with some Jupyter configuration files and version control those in a GitHub repository. 2. Jupyter book sofware allows you to compile an html version of the book locally (for testing) 3. Set up GitHub Action on book source repository to push changes to a GitHub Pages site of the book upon commits to master. 4. The html site for the Jupyter Book labs would be very accessible, LaTeX- and BibTex-like links and math rendering, and with a click of a button, the page will open as a local Jupyter notebook or Jupyter Lab hosted notebook or a CoLab hosted notebook with executable code and with a specified code environment. I think this is the sweet spot. We've moved all the documentation for a number of our open source projects over to Jupyter Books. The two following examples are still under development, but they are far enough along to show a lot of the functionality of the medium. - The Tax-Calculator project <https://github.com/PSLmodels/Tax-Calculator>'s documentation is shown in the associated GitHub page <https://pslmodels.github.io/Tax-Calculator/> in the upper-right corner. All the source code for that documentation is version controlled in the Tax-Calculator/docs/ <https://github.com/PSLmodels/Tax-Calculator/tree/master/docs> folder. Whenever a pull-request is merged that has commits to the files in that folder, a GitHub Action deploys the updated version of the documentation to the GitHub page. - Another example is the OG-USA <https://github.com/PSLmodels/OG-USA> model. The Jupyter Book documentation is at the GitHub page <https://pslmodels.github.io/OG-USA/content/intro/intro.html> associated with the repo, and the source for the documentation is in the OG-USA/docs/ <https://github.com/PSLmodels/OG-USA/tree/master/docs> folder. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#9>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAPQXLGXDSKQHZZPM6KDE6LSCFJMVANCNFSM4QIY5KRA> .