For example, the documentation to some project you've done in, say, Python, has been generated using something like Sphinx, or you've just got some html files.. Nonetheless, you want to host an online version of this documentation as a pre-built website on github.
This is especially useful if you've made some changes to the documentation/website of a Github repository, and you want to show it easily to your peers for review, without having them first fork it and build it in order to see what you've done.
Note that these instructions are from how I do it on ubuntu 11.10.
- Firstly, on your Github account (Your profile page where your forks and repositories are shown, create a new repository.
- Give it a name, like for example, project_documentation_online_build.
- A set of instructions should appear, the first them being Global setup, which I'm assuming you've hopefully done already. Follow the Next steps instructions in your terminal to create your directory with the same name (in my case, project_documentation_online_build). They should go a little something like this:
git add README
git commit -m'first commit'
git remote add origin email@example.com:YourUserName/project_documentation_online_build.git
git push -u origin master
You can then create a new branch for this repository called gh-pages like so:
git symbolic-ref HEAD refs/heads/gh-pages
- Switch to this branch:
git checkout gh-pages
- Now you can place all your html files here, like for example your html-build from your Sphinx generated documentation. Once you've placed it all here, you can:
git add .
git commit -a -m "First pages commit"
git push origin gh-pages
A wee bit later you should be able to check it at http://YourUserName.github.com/project_documentation_online_build/
Note1: If you're page built but it's missing it's theme and pretty colours, add a blank file called .no_jekyll to the main directory in your gh-pages branch and try pushing it again.
Note2: This is just what works for me. If you have any problems, I recommend you check out the GitHub Pages documentation. These instructions, together with those that are displayed upon creating a new repository, are pretty much what I'm summarising here.