Managing the online documentation

If you would like to edit the online content for echidna at https://snoplusuk.github.io/echidna/ or update the online documentation here, maybe after reviewing a pull request, then follow this guide.

Step 1: create an orphan copy of echidna tracking gh-pages

All the content for GitHub pages is stored on a special branch called gh-pages. In to make changes to this content we want to set up a clone of echidna that only tracks the gh-pages branch and has not history of any other commits. To do this:

1. Navigate to a local copy of echidna (either the copy used for development, or if you plan to update the documentation after merging a pull request, maybe a copy just for checking out pull requests as suggested in the guide to reviewing pull requests.)
2. The html documentation built by sphinx is located in docs/html (or at least it will be after [#59] is merged), this is excluded in .gitignore.
3. execute:

$ cd docs && rm -rf html/  # removes directory - we want it to be empty!
$ mkdir -p docs/html  # remake directory

• Now we want to turn this directory into an orphan git repository only tracking gh-pages:

$ cd html
$ git init
$ git checkout --orphan gh-pages
$ git branch
# should show no branches (not even master!)
$ 

• Set the remote and check there is no git history

$ git remote add origin [email protected]:snoplusuk/echidna.git
# Check you have no file .git/index, if you do delete it
$ rm .git/index
$ git clean -fdx  # removes any untracked files in the repository

You now have a fresh repository only tracking gh-pages and with no other echidna revision history.

Step 2 - remake the documentation

If you want to add content that is not sphinx documentation skip to Step 3.