Hey everyone, One thing I've been wanting to do for a long time is to automatically generate documentation for our JavaScript API. This should/would happen for every change we make.
For now I've been using the current (old) generation tool to explore this idea. It doesn't look very good [1] & isn't that useful atm but I just wanted to get the automation process right. The ultimate goal is to create something visually more appealing & useful like [2] or [3]. We will need to update to JSDoc3 [4], update the JavaScript annotations & create a new template. This will normally happen just after we make the formatting changes. The current automatic workflow: 1) Push a change to GitHub (currently the jsdoc branch of christian/3akai-ux [5]) 2) Trigger a POST to a Jenkins Hook [6] 3) Build the maven sakai-documentation profile [7] 4) Make a commit to the gh-pages branch of christianv/oae-jsdocs [8] 5) Build the GitHub page [1] We already have documentation for this API at [9] but the main issue with it, is that it's static. Which means we have duplication, it'll almost always be out of date & is not easy to maintain. Would love to hear your thoughts about this. Especially about what you would like to see & how I can improve the automatic workflow. So far I heard: - support for different OAE versions (Bert) - more examples within the docs (Scot) - Christian [1] http://christianv.github.com/oae-jsdocs/jsdoc/ [2] http://www.fullscale.co/jsdocs/c9.html [3] http://xueduany.github.com/jsdoc/out/$Kit.Animation.html [4] https://github.com/jsdoc3/jsdoc [5] https://github.com/christianv/3akai-ux/tree/jsdoc [6] https://sakai-oae.ci.cloudbees.com/github-webhook/ [7] https://github.com/christianv/3akai-ux/blob/jsdoc/pom-bundle.xml#L51 [8] https://github.com/christianv/oae-jsdocs [9] http://oae-widgets.sakaiproject.org/sdk/api/frontend _______________________________________________ oae-dev mailing list [email protected] http://collab.sakaiproject.org/mailman/listinfo/oae-dev
