This repository contains the source materials, as well as the authoring and publishing tools, of the textbook of the University of Chicago course Data Science I.
All textbook contents are generated from Jupyter Notebooks and Markdown files, converted by Jupyter Book into HTML, and served by GitHub Pages.
The published textbook may be accessed here.
Development of this textbook requires that you have pre-installed on your computer:
If you’re not sure, you can test for the presence of commands in your terminal as follows:
$ which docker python3.6 python3.7
Set up and check your environment for textbook authoring by sourcing the repository’s included Bash script:
$ source setup
The setup script will guide you through installation of any further required libraries.
If you use a shell other than Bash, you may instead execute the following setup command directly:
$ ./setup-install
However, this command is unable to affect your active shell; to correct this, you may simply start a new shell.
Set-up scripting attempts to guide authors in setting up their computers; however, your computer might vary considerably from expectations!
If you have both Docker and Python installed, the only further requirement is to install argcmdr.
This may be achieved generally via pip, e.g.:
$ pip install argcmdr
Then, the manage command should be available through your PATH:
$ which manage /path/to/manage
setup performs the above on your behalf, attempting to correct for environmental variability.
Issues with setup and the above instructions may be reported as Issues.
Having set up your textbook-authoring environment, you may manage it via the installed shell command, manage, (executed from the repository’s root directory):
$ manage [--help|...]
To begin a session, you’ll want to start the authoring servers:
$ manage start
The above command will ensure that the necessary Docker containers are built and running.
At the end of the output of the start command, you’ll see the URL of your local authoring server: a Jupyter server, for authoring plain-text content via Markdown files and programmatic/interative content via Jupyter Notebooks.
Textbook source files reside under the textbook/ directory. (The Jupyter server opens this directory by default.)
To preview local changes to these files, execute the build command:
$ manage build
The above command will generate HTML from the textbook source files, and write these under the preview/html/ directory. Your changes will then be available for preview.
|
Note
|
HTML files generated for local preview are not intended to be committed to the repository. (The |
Once you’ve completed your session, feel free to release computational resources by stopping the authoring servers:
$ manage stop
Consult the repository Wiki for more information on authoring content.
In particular, be aware of the provided Guidelines for:
-
branching and sharing your work on GitHub
-
avoiding merge conflicts
-
structuring your contributions to the textbook
GitHub Pages serves the textbook’s generated HTML at its configured domain.
The textbook is so published via the Github Actions workflow: Textbook (controlled via textbook.yml).
And the workflow is triggered – and the textbook published – by the publishing of a new Release.
|
Note
|
Release tags must follow the semantic versioning pattern: [0-9].[0-9]*. For example: 0.0.4.
|
If GitHub has a problem building what’s been committed, it will e-mail the user who authored the failing release.
The progress of the publishing workflow may otherwise be reviewed: Github Actions workflow: Textbook.
The textbook authoring- and build-environment is provided as a Docker container, the image of which is maintained under directory image/.
Changes to any files under that directory, once pushed to the repository, trigger the rebuild and push of that image, via the Github Actions workflow: Image (controlled via image.yml).