Thanks for your responses. I've put some comments inline: @Nico: > Looking at [1], it doesn't look like the current output is all that useful,
Yes, that seems very similar to what I mentioned: >> It doesn't look very good [1] & isn't that useful atm but I just wanted to >> get the automation process right. My mail wasn't really about the current output, just about the process. In order to improve the output we need to: >> update to JSDoc3 [4], update the JavaScript annotations & create a new >> template. > 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. Here and below you're repeating what I said on the UI Dev call, so I definitely agree. The thing we decided on was to wait with that until the formatting happened. > 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. That would indeed be ideal but I'm not sure yet what the best way to do this would be. We could perhaps expose a JSON structure that the SDK reads in, use an iframe or directly replace the HTML file and do that on every commit. I think each of those is possible but it's a tradeoff between time & ease of implementation. I created a jira ticket for this where we can continue the discussion for this particular feature [1] @Alan > For JavaDoc there is a JavaDoc diff tool that tells you what are the > differences between API versions. I dont suppose that that can built into the > autodoc generation? Afaik JSDoc3 doesn't have a tool for this feature yet but I really like the idea. The current process puts everything in GitHub so in theory it should be possible to create something like this. We could also start using the @since annotation. I also created an umbrella Jira to track the process of the most critical features [2] - Christian [1] https://jira.sakaiproject.org/browse/SAKIII-6030 [2] https://jira.sakaiproject.org/browse/SAKIII-6027 On Jul 20, 2012, at 3:53 AM, Nicolaas Matthijs wrote: > 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
