Data 140 Textbook

Data 140 Textbook#

This textbook was built with Jupyter Books. This README was written by Shahzar.

Structure#

Only three files/directories need to be edited.

  • _config.yml: Configuration information about the textbook. Modify this file for things like:

    • changing the logo or favicon;

    • adding or removing launch buttons;

    • changing information about the book.

  • _toc.yml: Table of contents for the textbook. Modify this file for things like:

    • section and chapter numbering and order;

    • adding or removing sections or chapters.

  • content/: Content of the textbook. All the notebooks with section and chapter content go here. Modify these files to actually change the content of the sections.

Maintaining the Textbook#

This section details how to maintain the textbook.

One-time Setup#

Follow these steps the first time you set up a computer to modify and maintain the textbook.

  1. Create a local copy of this repo by running git clone https://github.com/prob140/textbook.git from the command line in whichever folder you want to contain the textbook.

  2. Next, you need to install all the required packages. Either of the commands pip install -r requirements.txt or conda install --file requirements.txt should work. If you have a Windows device, it’s preferable to run this in an Anaconda Prompt terminal. This should install the two packages jupyter-book and ghp-import, which are used for building and deploying the textbook, respectively, and a bunch of other typical packages (e.g. numpy, scipy, matplotlib, etc.) used by the content/ notebooks.

Updating the Textbook#

These steps detail the process you should go through every time you update the textbook.

  1. Pull: cd into textbook/, your local copy of the textbook repo and git pull origin master to collect any updates which may have been pushed to the remote copy by other collaborators.

  2. Update: Make any changes you wish to make. This should (likely) only consist of changes to _config.yml, _toc.yml, and the files in content/.

    • If you added new sections or chapters, update _toc.yml as well to reflect your changes.

  3. Build: cd into the directory above textbook/ (i.e. cd ..) and run jupyter-book build textbook.

  4. Check: Open the file textbook/_build/html/index.html in your browser to view what the textbook will look like with any changes you’ve made. Make sure nothing is broken and the changes are as you want them.

    • See the Troubleshooting section for any issues you may be having.

    • Take a look at the Issues for problematic parts of the textbook.

  5. Deploy: cd back into textbook/ (cd textbook/) and run ghp-import -n -p -f _build/html (the -n flag is important, since it adds a .nojekyll file which allows GitHub to build the website correctly). This will push the _build/html folder to the gh-pages branch of the textbook repository, which is configured by GitHub Pages to hold the files for the textbook website. To edit these configurations, from the repository page, go to Settings > Pages.

  6. Push: Stage any changes you made (i.e. using git add [file], git add -u, git add ., etc.), commit your changes with git commit -m "[description]" (please include a useful description of any changes you made), and push to the master repository with git push origin master.

Notes#

Troubleshooting#

The (Jupyter Book)(https://jupyterbook.org/en/stable/intro.html) website has lots of information about Jupyter Book. Some useful pages are:

If changes you’ve made aren’t showing up the HTML after building, sometimes deleting _build and then building again helps. Jupyter Book will usually only re-build the HTML of notebooks that it thinks have been changed by any edits made, and so this sometimes means that some changes will go unnoticed. Deleting the entire folder and rebuilding forces it to build from scratch, which prevents any old files or code from sticking around.

Contents