Setting up Github Pages - tooltwist/documentation GitHub Wiki

Github Pages are website pages that Github will serve from their website, using a slightly different URL to the normal URL for a project. For example, if the normal project URL is

https://github.com/tooltwist/tea

then the Github Pages for the project would be

https://tooltwist.github.io/tea

The pages that will be served should be stored in the normal repository, in a branch named gh-pages, (but nothing else should be in the branch). For more information see here.

Github pages are an ideal place to display publicly available information about your project. For private repositories the wiki is not viewable except to team members, but the Github Pages are. Another advantage is that the Github Pages can be displayed from within an iFrame, making them accessible from tools like the ToolTwist Designer.

Common content for the Github Pages includes:

  • A nice introduction page for the project (Bootstrap?)
  • Widget documentation.
  • XDS descriptions, including sample inputs and outputs.
  • Documentation about RESTful services.
  • Javadoc for java libraries.
  • Javascript documentation, if relevant.

Editing pages on your local machine

We'll use Github's automatic page generator, then sync it down to our local machine where we can make changes.

  1. Go to your project on the github website and click on the Settings tab. On this page click on a button Automatic Page Generator. Create a nice home page for your website or, if you intend to use Jekyll later you can accept the defaults. Work through the screens, up to publishing the site.

  2. Create a github-pages directory under your project directory.

     $ cd devel/tea  
 $ git remote -v  
 origin	https://github.com/tooltwist/tea.git (fetch)  
 origin	https://github.com/tooltwist/tea.git (push)

Take note of the repository name, and substitute it into the following command:

$ git clone https://github.com/tooltwist/tea.git github-pages
Cloning into 'github-pages'...
remote: Counting objects: 140, done.
remote: Compressing objects: 100% (87/87), done.
remote: Total 140 (delta 34), reused 117 (delta 24)
Receiving objects: 100% (140/140), 633.92 KiB | 124 KiB/s, done.
Resolving deltas: 100% (34/34), done.

IMPORTANT: Check that you have an entry for github-wiki in .gitignore. If you don't, then the contents of the wiki will get uploaded into your main project repository as well as the wiki repo.

$ cat .gitignore 
.DS_Store
/solr-4.3.0
/app/node_modules
/documentation/restapis/_site
/github-wiki
/github-pages
/solr
/memcached

You will now need to switch the branch in the github-pages directory.

$ cd tea.pages
$ git checkout gh-pages
Branch gh-pages set up to track remote branch gh-pages from origin.
Switched to a new branch 'gh-pages'

You should now see the web files created by Github.

$ ls -l
total 16
drwxr-xr-x  6 philipcallender  staff   204 29 May 00:49 images
-rw-r--r--  1 philipcallender  staff  3761 29 May 00:49 index.html
drwxr-xr-x  3 philipcallender  staff   102 29 May 00:49 javascripts
-rw-r--r--  1 philipcallender  staff  2043 29 May 00:49 params.json
drwxr-xr-x  4 philipcallender  staff   136 29 May 00:49 stylesheets

Any time you change these files, you'll need to push them back to Github to be publish them.

$ git push

Modifying the Github pages

These files can be modified by hand, but more likely you'll want to modify them automatically. Here's a few possibilities:

  • Create a blog using Jekyll.
  • Have Maven generate Javadoc into this directory.
  • Use Carte to generate documentation for your REST interfaces.
  • Use JSDoc to generate Javascript documentation.

(see [here](Tools for defining, editing, and testing JSON) for more options).

Just remember, anything you push to the remote repository from your github-pages directory will be published on the Github site.