Building Documentation for GitHub Pages

Creating a GitHub project page

GitHub pages are built from a branch of the repository called gh-pages. If you have not already created a GitHub project pages for PyCBC in your repository, make a gh-pages branch in your repository as follows:

git checkout --orphan gh-pages
git rm -rf .
git clean -dxf
touch .nojekyll
mkdir latest
git add .nojekyll latest
git commit -a -m "set up gh-pages branch"
git push origin gh-pages
git branch --set-upstream gh-pages origin/gh-pages

These commands create the branch and then remove all of the files from this branch, so that it will just contain the documentation pages.

Note

The main gwastro/pycbc repository already has a gh-pages branch, so do not do this in the main repository.

Building and pushing the documentation

The documentation should built from the source code on a regular branch and installed into the gh-pages branch. Since git cannot have two branches checked out simultaneously, you need to check out another copy of the repository with the gh-pages branch inside your PyCBC source repository. Do this will the following commands (assuming your PyCBC git repository is in a directory named pycbc).

cd /path/to/your/repo/pycbc
git clone git@github.com:github-username/pycbc.git _gh-pages

Now flush the contents of this directory. We do this, as the documentation is not really under version control in the gh-pages branch. We just use this branch to publish to GitHub pages. Run the commands

cd _gh-pages
git rm -rf *
git commit -a -m "flush documentation"
cd ..

The last cd command should put you back at the top level of your PyCBC source directory. To build the documentation into the _gh-pages directory, run the command

python setup.py build_gh_pages

This will build the documentation in the second repository that you created called _gh-pages under the directory latest/. To push these changes up to GitHub

cd _gh-pages
git add --all
git commit -a -m "documentation update"
git push origin gh-pages

The documentation will then be available under your GitHub pages at http://username.github.io/pycbc/latest/html/ where you should replace username/ with your GitHub account name.

In this example, we checkout the master branch to build the documentation, but you can change the last command above to checkout any other branch that your are developing.

Note

Be careful with the git rm -rf * command as if you run it in the wrong directory you can delete the contents of your git repository. If you do this by accident, you can use git reset to undo the commit.