Hey Bert, Thanks for making these suggestions.
In general I really like the ideas, my only worry is that some of the things might take a while. My initial hope was to get something that would be useful for front-end devs up and running quickly. I do agree that they should be goals we should try to meet, I'm just not sure how much time we want to spend on those. Also some comments inline: > Expose a JSON Feed to the widget SDK that renders the documentation (uses > same style as the rest of the SDK) This is one of the ways we can do it, another way would be to generate the .html.erb file directly. I'm not sure which way will be the best (easiest to implement/maintain). > When a release is cut the documentation for that release should be generated > and archived; and > It’s important to keep in mind that a lot of people won’t be developing on > the current master branch but on a release. The default API documentation > shown should be the documentation for the latest release. People can still > switch to the documentation for the master branch if they would like to. Yes, that's one of the reasons why I created a separate GitHub project for this. [1] When we tag it, people will be able to download just the documentation from the tags page (e.g. [2]). > Make documentation downloadable (PDF/Print CSS) We could go for a PDF option (e.g. [3]) but imo print CSS should suffice. > Use the Widget Library server to generate documentation I'm not sure whether I fully understand how this would work. Would you add a GitHub commit hook to the Widget Library server and then generate the documentation? It would probably be good to limit the amount of things that are running on the server > I will convert the feedback on this proposal to JIRA tickets I already created the initial Jira tickets before getting your response [4] (also see linked jira). As I already said before, imo it's more important to have useful docs then to be feature complete. - Christian [1] https://github.com/christianv/oae-jsdocs [2] https://github.com/sakaiproject/3akai-ux/tags [3] https://github.com/prawnpdf/prawn [4] https://jira.sakaiproject.org/browse/SAKIII-6027 On Jul 24, 2012, at 2:03 AM, Bert Pareyn wrote: > > Hey all, > > To make the JSDocs available in a better way there’s a couple of things we > could do. There’s a few things we need to take into account when implementing > this and making it available to the public. > Keep the documentation up to date by regenerating it on every commit; > Expose a JSON Feed to the widget SDK that renders the documentation (uses > same style as the rest of the SDK) > When a release is cut the documentation for that release should be generated > and archived; > Keep the documentation in a place where all developers will find it (Widget > SDK) > Make documentation downloadable (PDF/Print CSS) > Use the Widget Library server to generate documentation > Keeps the docs in one space, easier maintenance > In the long run we want to move other documents to this space as well > (Release notes etc.) > It’s important to keep in mind that a lot of people won’t be developing on > the current master branch but on a release. The default API documentation > shown should be the documentation for the latest release. People can still > switch to the documentation for the master branch if they would like to. > > The structure in the SDK could be something like: > API & Endpoints > Front-end API (this would be the latest release) > Back-end endpoints (this would be the latest release) > 3rd party libraries > Previous releases and trunk (This could have pages of documentation or just a > zip file containing the archived documentation) > I will convert the feedback on this proposal to JIRA tickets by the end of > the week, all suggestions and improvements are welcome. > > - Bert > > On 23 Jul 2012, at 10:15, Bert Pareyn wrote: > >> >> Hey Christian, >> >> Thanks for bringing this to list. >> For the documentation to be more useful than just grabbing the code and >> reading the JSDoc the formatting should change (as you already pointed out, >> +1). >> It should be available in a place where developers will go to when creating >> a widget (the widget SDK), not on yet another different URL. >> As Nico mentioned, the API's are the functions we really want to have that >> documentation for. >> >> I think that in the long run, we'll want to move release documentation and >> all docs related to it to the SDK as well. >> That means having a separate section that shows the generated docs for each >> release version as well as a description of what's changed (basically the >> same as goes on to the Sakai project site and listS now, but archived and >> consolidated in one place). >> I think the idea of having a JSON structure available to the widget library >> is a good idea. Maybe we can make use of the widget library server to >> generate the documentation. >> >> - Bert >> >> On 20 Jul 2012, at 19:36, Christian Vuerings wrote: >> >>> 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 >> >> _______________________________________________ >> 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
_______________________________________________ oae-dev mailing list [email protected] http://collab.sakaiproject.org/mailman/listinfo/oae-dev
