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.
Themes are used to set the design standards of a website, such as fonts and colors. The theme we use is
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.
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
curriculum-book-template. You can do so by reviewing layout.html in
sphinx-bootstrap-theme and making the appropriate changes in
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:
Clone bootswatch to your computer.
Locate the theme you are planning on updating.
launchcodecontains the styles for sites hosted on education.launchcode.org.
Within the directory for the theme you are hoping to update, update
variables.lesswith the necessary changes.
At the project root, run
At the project root, you will find
index.html. Check out that file to see your changes.
When you are confident in your changes, commit them to
Post-build of your updates to
bootswatch, copy the contents of the file,
bootstrap.min.cssin your theme directory.
sphinx-bootstrap-themeand paste the updated contents of
bootstrap.min.cssin the coordinating theme directory. Push the changes to the default branch.
To see the updates, run the update command.
curriculum-book-template is the template which all of our books are built on. The template includes:
General settings configured in
General settings for Travis, our CI tool.
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
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.