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
$ 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 : username.github.io/repo_name
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.
Install Docco with npm:
sudo npm install -g docco
Run it against your code:
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.