How Sphinx Works

Sphinx is a static site generator that is based on Python and RST. Our Sphinx sites incorporate several different elements that you have already installed. These elements can be placed into three different buckets: the theme, the template, and the continuous integration (CI) tool. Templates are used to set the layout of a website, such as the navbar. We use a CI tool to build the curriculum sites so that if a bad build is pushed to the repository, a previous version of the site will remain live for the students.

The Theme

Themes are used to set the design standards of a website, such as fonts and colors. The theme we use is sphinx-bootstrap-theme. sphinx-bootstrap-theme controls what styles are passed to the sites. The LaunchCode version is a fork so we regularly pull in updates from the upstream if we are getting too far behind. When updating sphinx-bootstramp-theme, you should be cognizant of the versions of any of the included packages, such as Bootstrap and JQuery, have changed. If so, you need to update layout.html in curriculum-book-template. You can do so by reviewing layout.html in sphinx-bootstrap-theme and making the appropriate changes in layout.html in curriculum-book-template. Fetching changes from the upstream constitutes most updates made to sphinx-bootstrap-theme, except for changing colors.

To change the colors specifically, you have to do the following steps to ensure that sphinx-bootstrap-theme gets the changes:

  1. Clone bootswatch to your computer.

  2. Locate the theme you are planning on updating. launchcode contains the styles for sites hosted on education.launchcode.org.

  3. Within the directory for the theme you are hoping to update, update variables.less with the necessary changes.

  4. At the project root, run grunt swatch.

  5. At the project root, you will find index.html. Check out that file to see your changes.

  6. When you are confident in your changes, commit them to lc_stable.

  7. Post-build of your updates to bootswatch, copy the contents of the file, bootstrap.min.css in your theme directory.

  8. Open sphinx-bootstrap-theme and paste the updated contents of bootstrap.min.css in the coordinating theme directory. Push the changes to the default branch.

  9. To see the updates, run the update command.

The Template

curriculum-book-template is the template which all of our books are built on. The template includes:

  1. General settings configured in conf.py.

  2. General settings for Travis, our CI tool.

  3. launchcode.css, which is used to set the colors and styles for our code blocks. At the time of writing, we do not have a branded Pygments theme so we have to overwrite the Pygments styling at the template level.

If you make a change in one book that the other books would benefit from, make sure to apply that change to curriculum-book-template. To pull in updates to the template to the book you are working on, fetch the changes from the upstream.

The CI Tool

We use Travis for our CI tool. When you push commits to the default branch, Travis builds the site and pushes the build to gh-pages. The content on gh-pages is what is deployed to the site. If an update is made to sphinx-bootstrap-theme, Travis will fetch the updates. However, if changes are made to the curriculum-book-template, you have to fetch those changes when working on your local copy and push them to the default branch to see them on the live site.