Show-off With GitHub and Docco

I was experimenting with some documentation styles today and discovered two bits of gold: gh-pages and docco:

Creating a site for your project using GitHub is a 3 step process: 1. create a new orphan branch called gh-pages 2. remove all the contents 3. fill the branch with your boastful new site

$ cd repository

$ git checkout --orphan gh-pages
# Creates a branch, without any parents
# Switched to a new branch 'gh-pages'

$ git rm -rf .
# Remove all files from the old working tree

From here you can use the GitHub Automatic Page generator to throw up a theme and some standard content, you can roll out a jekyll bootstrap platform with blogging integration, or you can simply:

$ echo "Hello gh-pages!" > index.html
$ git add index.html
$ git commit -a -m "First pages commit"
$ git push origin gh-pages

Add and commit your content to your gh-pages branch, and GitHub will generate what needs to be generated in order to serve your website.

Your pages are hosted for free by GitHub. If you have already configured a personal site using User Pages, your project pages will hang off the end of your domain like this :


Docco is a quick-and-dirty documentation generator, written in Literate CoffeeScript. It produces an HTML document that displays your comments intermingled with your code. All prose is passed through Markdown, and code is passed through Highlight.js syntax highlighting.

Docco works with Python, Ruby, JavaScript, Java, and many other languages, with no configuration — just plug and play!

Install Docco with npm:

sudo npm install -g docco

Run it against your code:

docco lib/*.ruby

Docco will create a docs/ folder in your project and will generate an html file for each ruby file in the lib directory. This is where beautifully commented code really pays off, but docco does not format multi-line code the same way. Check out my benchmark.rb for an example of how each comment style is treated by docco.