+1. Before embarking on this work, we need to have a very clear
strategy for how we get the generated documentation into the Widget
Library and execute aimed at that goal, without getting too distracted
by other methods of delivering the documentation.
Thanks,
Nicolaas
On 24 Jul 2012, at 10:03, 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
