Building Documentation for GitHub Pages¶
Creating a GitHub project page¶
GitHub pages are built from a branch of the repository called
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.
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
cd /path/to/your/repo/pycbc git clone firstname.lastname@example.org: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 ..
cd command should put you back at the top level of your PyCBC
source directory. To build the documentation into the
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.
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.