On 09/12/2013 07:50 AM, Martin Kosek wrote:
On 09/11/2013 11:24 PM, Dmitri Pal wrote:
On 09/11/2013 12:28 PM, Simo Sorce wrote:
On Wed, 2013-09-11 at 12:44 +0200, Petr Vobornik wrote:
This is a part of documentation effort which started couple month
Attached patches improves devel documentation of Web UI. Mostly by
annotating source code and then processing it by JSDuck tool.
The documentation is not complete - most plugins and member of some
widgets and facets are not annotated yet. I'm sending it now because
need to focus on more pressing tickets.
You can see current state at my fedorapeople page .
I also converted 5 guides/articles which I wrote some time ago.
are also part of the JSDuck app .
The idea is to regularly generate the doc and place it on
docs.freeipa.org (not in production at the moment) so all doc would
on one place.
Installation of JSDuck is documented on their page . Basically it
requires ruby and JSDuck gem.
$ cd install/ui/doc
Documentation is generated into: install/ui/build/code_doc directory
I would rather not grow a dependency on Ruby in the freeIPA project.
Are there any alternatives ?
Is it dev side dependency? We might have issues if we need gems during
build process that are not a part of distro.
This a UI Doc building dependency, i.e. not needed when package is installed.
So someone/something doing a release and releasing the doc will need the ruby +
respective rubygem installed.
If we want to automate the build and let the doc be built for example on koji,
I am afraid we would have to step back from using jsDuck, or let Petr package
it in Fedora since he used it despite my previous warnings :-)
The question is if we want to include these docs into some freeipa-doc
package. I don't think it's necessary. The important thing is to have it
on the web.
JSDoc <https://github.com/jsdoc3/jsdoc> <http://usejsdoc.org/>
- runs on rhino or can be downloaded by npm
- doc comments need to be too verbose (problems with introspection of
old class system)
- output is much worse then jsduck (can't find online example, the one
which I generated is already gone)
- requires .NET
- requires node.js
+ nice output <http://yuilibrary.com/yui/docs/api/classes/Graph.html>
- doesn't do code introspection - every information has to be in doc comment
- don't like the output <http://people.apache.org/~jkuhnert/>
+ packaged (not sure about JS support)
- the output is pretty bad <http://jsunit.berlios.de/classes.html>
- output requires php
+ nice output <https://dojotoolkit.org/api/>
~ not sure about code introspection, most likely works only with Dojo
+ IMO best output
+ sufficient code introspection - Works with older and new code
+ fast (compare to JSDoc)
Subjective comparison in specific areas:
- Writing doc comments:
JSDuck > YUIDoc | DojoDoc | NaturalDocs > JSDoc > Doxygen
- Output (UX)
JSDuck > YUIDoc | DojoDoc > NaturalDocs > JSDoc > Doxygen
NaturalDocs | Doxygen > JSDuck | YUIDoc > JSDoc > DojoDoc
Petr, we should think if we should keep UI doc and articles in devel repo or if
leave just the anonated code there and move all development articles and guides
to our new doc repo
The move can be considered only if we want to package the code doc. And
we might then require freeipa repo for doc generation which is not good.
To avoid it we would have to remove guides from the output app. It's bad
because it would break or make more difficult links from code  to
guides and vice versa.
Freeipa-devel mailing list