Hi Christian, Looking at [1], it doesn't look like the current output is all that useful, which is often the case with automatically generated documentation. I would suggest that we focus on what is really useful and what people (especially outside the project) really need. In my mind, this means not exposing the documentation of individual widgets, as most of those are internal methods, and focussing on exposing the documentation of our core API functions.
Once we do that, I think it makes sense to think about how we can feed the documentation seamlessly into the Widget SDK, as it would be good if we could continue to use that as a single point of information for widget developers and not introduce another location where data can be found. Hope that helps, Nicolaas On 20 Jul 2012, at 04:58, Christian Vuerings wrote: > 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 _______________________________________________ oae-dev mailing list [email protected] http://collab.sakaiproject.org/mailman/listinfo/oae-dev
