Building the Cyclus website requires:
- Sphinx v1.1.2 or higher
- sphinxcontrib-bibtex v0.3.0 or higher
- Cloud Sphinx Theme
NOTE: The cloud package for Debian and Ubuntu is broken, so do not apt-get
pip install cloud_sptheme,
easy_install cloud_sptheme, or install from source instead.
Modifying the Cyclus Website
A 2 branch system has been implemented to maintain a clean process of rebuilding this site.
1. The source branch contains the restructured text documents and Sphinx configuration used to build the site. All direct editing of files should be made in the source branch.
2. The master branch contains the processed and published web content that is derived by Sphinx from the source branch. These files should not be editted directly.
The rest of this readme assumes that you have two remotes associated with cyclus.github.com.
- Your fork, called
- The upstream Cyclus group remote, called
If you simply want to build the documentation and are on the source branch, you may always run:
Or if you have docker, you can forget about the other dependencies and just run:
There are docker targets in the makefile for doing everything related to the
site - building, previewing, and publishing. See the
Docker section below
for more details.
Best practice workflow for contributing to site changes
Checkout the source branch
git checkout source
Synchronize your branch with the repository (either pull or fetch and merge)
git pull upstream source
Create a branch to contain your change
git checkout -b add_some_info
Make your changes in this branch
Test your changes by using the gh-preview target
This will build a version of the site in the gh-build directory of your branch, add_some_info. You can load it directly in a local browser. Or if you have docker installed, you can optionally use the docker preview target:
to build the website inside a docker container with all the correct dependencies and configuration taken care of automagically.
Repeat steps 4-5 until satisfied.
Once satisfied with the source RST files, push your branch to your fork of the repo. Be sure to synchronize with any possible changes to the upstream repo source branch first.
git fetch upstream git rebase upstream/source git push origin add_some_info
Issue a pull request by going to your branch on your fork of the repo and clicking the "Pull Request" button.
Best practice for managing a pull request
Synchronize your repository with the upstream repo:
git fetch upstream git checkout master git merge upstream/master git checkout source git merge upstream/source
Checkout the pull_request_branch in the pull request submitter's repo:
git fetch https://github.com/[username]/cyclus.github.com pull_request_branch git checkout -b pull_request_branch
Test the changes by using the gh-preview target
This will build a version of the site in the gh-build directory in your branch, pull_request_branch. You can load it directly in a local browser.
If satisfied, merge the pull_request_branch into the source branch:
git checkout source git merge pull_request_branch
If there are no conflicts, push this to the repo
git push upstream source
Republish the pages with the gh-publish target.
make docker-... targets require the cyclus/fuelcycle.org-deps docker image
which can be retrieved/updated by running:
docker pull cyclus/fuelcycle.org-deps
Occasionally (i.e. for a Cyclus release) the image will need to be updated. This can be done by:
cd docker/fuelcycle.org-deps # update the image the fuelcycle.org image depends on docker pull cyclus/cymetric # rebuild the image docker build -t cyclus/fuelcycle.org-deps . # push the new image to docker-hub docker push cyclus/fuelcycle.org-deps
The website has functionality for allowing visitors to submit and run Cyclus
simulations in the cloud. Files and instructions for deploying/updating the
remote execution back-end functionality are in the
directory of the http://github.com/rwcarlsen/cloudlus repository.