github has an apps platform
So when Nick told me about his http://rdoc.info project for generating Ruby documentation with YARD it hit me immediately. Like a ton of bricks in the face. The place for documentation about GitHub projects is on GitHub. Why had they never built it in? Then I realized, they didn't need to. We could do it ourselves.
The concept was simple enough: register the user name "docs" on GitHub and create a GitHub Pages repository. This would allow us to publish content to http://docs.github.com. So I hacked around on a prototype (borrowing every image, stylesheet and layout I could from the exsiting GitHub site) and we came up with something that looked pretty good.
We realized though, that we would need to get permission from GitHub to do this before we showed anyone. So we took everything to Rails conference and met up with them over whiskey in the Star Trek lounge. They instantly got it, gave us the go ahead, and started talking about what would need to happen for it to really work well. We grabbed some beers, paired up with Joe and started hacking some more.
It turns out it's really hard to go back to static websites with no server-side code. But with GitHub pages you have to do just that. So we built a couple of clever JavaScript libraries for accessing repository and commit information from the API. We also made use of the 404.html page that you get with GitHub Pages. Add a couple of meta-redirects and one cross-site post and you have something that feels pretty normal.
When you search for a repository that has not been generated yet you are pushed to the 404.html where there is a form for generating. After entering the information, we check that the repository really exists and then post to http://rdoc.info. Everytime it generates documentation for a project it simultaneously generates pages using our custom GitHub YARD template and pushes it to the "docs" repository. We tell it that we want a redirect to our "generating" page so you don't notice that you left.
For the documentation itself, we maintain separate copies of the documentation per commit SHA. This allows you to have links to various versions of documentation which are static and permanent. For each page we added a namespaces button and methods button instead of using frames.
When you view source for a given method, there is a link back to the actual revision of the file in the repository. This allows you to quickly see specific source areas in context.
We are eager for feedback; please comment here or send us a message on GitHub.
4 comments
Jump to comment form | comments rss [?]