The YUI Gallery has nearly 250 modules, as of this writing. With some notable exceptions, it appears that very few of those modules have much in the way of documentation. This is unfortunate, because creating even simple documentation using YUIDoc is dead simple.

One of the features of Github that is very convenient are pages. Creating a branch named gh-pages inside of any repo pushed to github will cause Github to create a subdomain for you at username.github.com and will push to the repo name subdirectory. For myself, my yui3-gallery documentation appears at http://foxxtrot.github.com/yui3-gallery/. This can also be set up by enabling the "GitHub Pages" feature in the administrative settings of your repo.

Writing YUIDoc Comments is beyond the scope of this post. But you should be documenting your code, and you might as well do it in a way that you declare usable metadata with them.

The easiest way to build API Documentation is using Dav Glass' git-yui tool, which if you're working with YUI's source you should probably have anyway. git-yui provides tools for doing pretty much anything you might need to do, grabbing other users changes, syncing your repo with them, building modules, documentation, pull requests, jslint, etc. It does a lot, but it makes almost all of it trivial.

To start, you'll need to clone the following git repositories from YUI:

1. yui3-gallery
2. builder
3. yuidoc

These should all be cloned to the same folder.

Finally, just enter the yui3-gallery folder and run git yui docs <modules>, so for me in my current push that is git yui docs gallery-nodelist-extras gallery-node-extras. Once this runs, there will be a yui_docs folder in the root above your gallery directory. Checkout the gh-pages branch in your gallery module, and copy yui_docs/html into the root, checking in all the files.

For me, this process looks like this:

        craig@majikthise:~/project/web/yui/yui3-gallery/$ git checkout master
        craig@majikthise:~/project/web/yui/yui3-gallery/$ git yui doc clean
        craig@majikthise:~/project/web/yui/yui3-gallery/$ git yui doc gallery-nodelist-extras gallery-node-extras
        craig@majikthise:~/project/web/yui/yui3-gallery/$ git checkout gh-pages
        craig@majikthise:~/project/web/yui/yui3-gallery/$ cp -R ../yui_docs/html/* .
        craig@majikthise:~/project/web/yui/yui3-gallery/$ git commit -a -m "YUIDoc Update"
        craig@majikthise:~/project/web/yui/yui3-gallery/$ git push
        

I am looking to extend Dav's git-yui script to allow you to do git yui doc my which will query YUI Library for a list of gallery modules you own and build docs for those, but I'll need to do some tests to ensure that works, since I know I've only properly documented 2 of my 5 modules.

The other side of this is if you want to include examples. In that case, you should probably put the YUIDoc generated files into the /api/ folder in your gh-pages branch, and then you can build more detailed documentation in the root. The point is, that even without high-quality prose-like documenation, API docs are easy to generate, and they should prove to make your modules easier to use and maintain.