Hosting your html on Github

If you want to host a webpage on Github, here's how I do it.

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.

1. Firstly, on your Github account (Your profile page where your forks and repositories are shown, create a new repository.
   
2. Give it a name, like for example, project_documentation_online_build.
3. 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:
   
   mkdir project_documentation_online_build
cd project_documentation_online_build
git init
touch README
git add README
git commit -m'first commit'
git remote add origin git@github.com:YourUserName/project_documentation_online_build.git
git push -u origin master


4. You can then create a new branch for this repository called gh-pages like so:
   git symbolic-ref HEAD refs/heads/gh-pages
   
   
5. Switch to this branch:
   git checkout gh-pages
   
   
6. 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

Once you've done this, you should receive a message from Github to inform you that your pages has been succesfully built (usually after a couple minutes).
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.

Cycling with Jinga

I was tweaking the layout.html file for Python's Sphinx and found the following random tit-bit of use when using Jinga:


{%- for rellink in rellinks[1:]|reverse %}
  <div class="{{ loop.cycle('buttonPrevious', 'buttonNext') }}">
   <a href="{{ pathto(rellink[0]) }}">
    {{loop.cycle('Previous', 'Next')}}
  </a>
{%- endfor %}




With loop.cycle you can cycle through strings or divs
as the loop iterates..

In the above example, a div is created first for buttonPrevious and then
the next iteration for buttonNext. The same applies to the strings that determine what gets
printed on the button.

doctest_mode in iPython

If you want to import code into iPython that has been copied from the python console
or code that is to be run as a doctest in Python Sphinx, a useful trick to use in iPython
is

%doctest_mode

For example:

>>> import numpy as np
>>> some_value = 35
>>> np.sqrt(some_value)


You can copy this directly into iPython and it will treat it like normal python code.
No need having to copy every line of code after >>>