The data-8 textbook, a Jupyter Book source behind inferentialthinking.com

The book is a build artefact, not the repository

The data-8/textbook repository holds the Jupyter Book source for Computational and Inferential Thinking: The Foundations of Data Science. The important thing to understand first is that the book you read at inferentialthinking.com is not in this repository. The HTML is pushed to a separate repository, github.com/inferentialthinking/inferentialthinking.github.io, and the README is emphatic that nobody should edit that repository directly.

The division exists because of how the deployment works. The source lives here, on the main branch of data-8/textbook, and a GitHub Action takes the built HTML and pushes it to the inferentialthinking.github.io repository, which is what GitHub Pages serves. The action is the file .github/workflows/deploy.yml. The CNAME file at the top level is part of the same arrangement, since it is how the custom domain is bound to the Pages site.

So the contributor workflow is a normal fork, branch, pull request, merge cycle. The README spells it out: clone the repository, change the file you wish and commit it, push your change back to the data-8/textbook repository, ideally via a pull request, and a GitHub Action takes care of the build and the deploy to inferentialthinking.com. The last step is described simply as that is it, which is true but hides the one part of the workflow that will bite you if you skip it, which is the alt text.

The primary language of the repository is Jupyter Notebook, which is the point of the whole project rather than an incidental detail.

chapters/ holds notebooks that are executed when the book is built

The layout of the repository is a Jupyter Book project. The chapters/ directory holds the chapters, _static/ and images/ and assets/ hold the styling and figures, footer.md holds the page footer, and myst.yml is the MyST configuration that turns Markdown and notebooks into the site. There is an environment.yml alongside, which is the conda environment for the course, and a.binder/ directory, which points to the Binder setup for running the notebooks without a local install. The scripts/ directory holds the auxiliary tooling the book needs.

The build dependencies are listed in requirements.txt:

jupyter-book>=2
mystmd
numpy
datascience
matplotlib

That short list tells you a lot about how the book is produced. jupyter-book is the site generator, mystmd is the Markdown dialect that lets prose and notebooks live in the same project, and numpy, datascience and matplotlib are the libraries the notebooks themselves use. The datascience library is listed alongside numpy and matplotlib as a notebook dependency, and the repository's home in the data-8 organisation points to the data-8 course behind the book.

Because the chapters are notebooks and they are executed as part of the build, the numbers, plots and outputs a reader sees are recomputed rather than pasted. That is the strongest argument for the format: the book cannot drift from the code, because the code runs every time the site is deployed. It is also the source of the project's sharpest operational wrinkle, which is what happens to the figures when they are recomputed.

A plot rebuild wipes the alt text unless you restore it

The README spends a full section on something that looks like a footnote and is in fact the most distinctive part of contributing to this book. Alt text has been manually added for matplotlib outputs because there is no built-in way to set it. The warning is that if you edit or run a cell with matplotlib output, the alt text may be overwritten, and the responsibility for keeping it falls on whoever made the edit.

The mechanism is specific. With the notebook open in VSCode, you use More Actions, the three dots in the cell menu, and choose Edit Cell Tags (JSON) to open the raw notebook file. In that JSON you find outputs.data.text/plain, which for a default matplotlib figure holds a placeholder value such as <Figure size 432x432 with 1 Axes>. That value is what becomes the alt text for the plot in the deployed book, so you replace it with a real description of the plot. If the plot already existed in the textbook, the instruction is to look for what was written before by searching pull requests for Ch N Better Alt Text, with N being the chapter number, and to reuse that text if it still fits.

That instruction is a small but revealing piece of project design. Accessibility text lives in a pull request history rather than in a separate file, which means it is reviewed and versioned with the change that introduced it. The repository also runs an accessibility checks workflow, and a Jupyter Book deployment workflow, both visible as badges at the top of the README.

For a contributor, the practical rule is simple. If you touch a cell that draws a figure, open the cell JSON and set outputs.data.text/plain to a description of what the plot shows, then check your diff.

Building the book on your own machine

The local build is documented in one line, install the requirements and then run the Jupyter Book build command:

pip install -r requirements.txt

jupyter-book build .

The README also points to the Jupyter Book guide for the build instructions, since the CLI has more options than the two commands above, and it links the Jupyter Book build instructions page for the details of how to use the CLI to build the book.

The build output directory and the preview command are not spelled out in the README, so the local loop is: install, build, and serve the built site with whatever Jupyter Book offers for previewing. If you want to work on the notebooks interactively rather than reading the rendered book, the conda environment in environment.yml and the .binder/ directory are the two routes the repository offers for a ready-made runtime.

One thing the local build does not reproduce is the deployment half of the pipeline. Pushing to main triggers the GitHub Action, which builds the book and pushes the HTML to the inferentialthinking.github.io repository that GitHub Pages serves. A local build gets you the artefact, not the deployment.

What this repository is for, and who it is not for

This is a repository for maintaining an existing book, not for reading one. That distinction is easy to miss from the outside, because the book is famous and the repository is the canonical address people land on.

For a reader, the repository is the wrong place. The README does not describe the book as a downloadable PDF or a set of slides, and the deliverable is a website built by Jupyter Book and served from GitHub Pages. If you want to work through the chapters, inferentialthinking.com is the place to work through it, and the notebooks can be run through Binder for the hands-on parts.

For a contributor, it is a narrow but pleasant task. Fix a wrong statement, improve a figure, or improve the explanation of a concept, in Markdown prose or in a notebook, then open a pull request against main. The build and deploy are automated, so there is no publishing step to negotiate.

The limitation that shapes all of this is that the content is executed rather than merely rendered. A chapter that depends on a data file, a network call or a specific library version can behave differently on the deployment runner than it does in your local environment, and the README does not document a pinning strategy for the chapter environment beyond the requirements.txt list and the conda file. Contributors editing code cells rather than prose should expect to verify the rendered result rather than assume the notebook ran as intended.

Editorial conclusion

The data-8/textbook repository suits contributors to the data-8 course who want to fix a chapter, improve a figure or correct an explanation and see it on inferentialthinking.com within a deployment cycle. It does not suit readers looking for a PDF, since the book is a web project served from GitHub Pages, and it does not suit contributors who are not prepared to handle the alt text requirement for matplotlib outputs. Before you open a pull request, read the alt text section of the README, check the chapter number so you can look for the matching Ch N Better Alt Text pull requests, and confirm the build works locally with pip install -r requirements.txt and jupyter-book build .

Frequently asked questions

Official sources

1. data-8/textbook on GitHub
2. Issues
3. Project website
4. README