jhumpherys
commented
4 years ago This is a great idea Rick. We should do it.
On Sun, Aug 23, 2020 at 11:52 AM Richard Evans notifications@github.com 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.
- Write content as markdown file (.md) along with some Jupyter configuration files and version control those in a GitHub repository.
- Jupyter book sofware allows you to compile an html version of the book locally (for testing)
- Set up GitHub Action on book source repository to push changes to a GitHub Pages site of the book upon commits to master.
- 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 https://github.com/Foundations-of-Applied-Mathematics/Labs/issues/9, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAPQXLGXDSKQHZZPM6KDE6LSCFJMVANCNFSM4QIY5KRA .
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.
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.