[Freeipa-devel] [PATCH] 451-458 Web UI devel and source code documentation

[Simo Sorce]

On Thu, 2013-09-12 at 11:02 +0200, Petr Vobornik wrote:
> 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:
> >>>> Hello,
> >>>>
> >>>> This is a part of documentation effort which started couple month
> >>>> ago.
> >>>> Attached patches improves devel documentation of Web UI. Mostly by
> >>>> annotating source code and then processing it by JSDuck tool[1].
> >>>>
> >>>> The documentation is not complete - most plugins and member of some
> >>>> core
> >>>> widgets and facets are not annotated yet. I'm sending it now because
> >>>> I
> >>>> need to focus on more pressing tickets.
> >>>>
> >>>> You can see current state at my fedorapeople page [2].
> >>>>
> >>>> I also converted 5 guides/articles which I wrote some time ago.
> >>>> Guides
> >>>> are also part of the JSDuck app [3].
> >>>>
> >>>> 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
> >>>> be
> >>>> on one place.
> >>>>
> >>>> Installation of JSDuck is documented on their page [4]. Basically it
> >>>> requires ruby and JSDuck gem.
> >>>>
> >>>> Usage:
> >>>> $ cd install/ui/doc
> >>>> $ make
> >>>>
> >>>> Documentation is generated into: install/ui/build/code_doc directory
> >>>>
> >>>> [1] https://github.com/senchalabs/jsduck
> >>>> [2] http://pvoborni.fedorapeople.org/doc
> >>>> [3] http://pvoborni.fedorapeople.org/doc/#!/guide
> >>>> [4] https://github.com/senchalabs/jsduck/wiki/Installation
> >>>
> >>> I would rather not grow a dependency on Ruby in the freeIPA project.
> >>> Are there any alternatives ?
> >>>
> >>> Simo.
> >>>
> >> 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.
> 
> Short overview of other JavaScript doc tools
> 
> 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)
> - slow
> 
> ScriptDoc/AjaxDoc http://ajaxdoc.codeplex.com/
> - requires .NET
> 
> YUIDoc http://developer.yahoo.com/yui/yuidoc/
> - 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
> 
> NaturalDocs http://www.naturaldocs.org/
> + packaged
> - only basic JavaScript support (no code introspection)
> - don't like the output <http://people.apache.org/~jkuhnert/>
> 
> Doxygen
> + packaged (not sure about JS support)
> - the output is pretty bad <http://jsunit.berlios.de/classes.html>
> 
> Dojo Doc
> - output requires php
> + nice output <https://dojotoolkit.org/api/>
> ~ not sure about code introspection, most likely works only with Dojo 
> classes
> 
> JSDuck
> - ruby
> + 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
> 
> - Packaging
>    NaturalDocs | Doxygen > JSDuck | YUIDoc > JSDoc > DojoDoc
> 

To be honest, I would go with the old and tried doxygen, maybe we can
find a way to make the output not look too bad ?
The output you link up there is the worst thing I have ever seen, but it
is not what I have seen in most other doxygen generated outputs.

This one doesn't look bad:
https://talloc.samba.org/talloc/doc/html/group__talloc__ref.html

This is also generated by doxygen and looks ok to me:
http://dbus.freedesktop.org/doc/api/html/index.html

> >
> > 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
> > http://www.freeipa.org/page/Contribute/Documentation
> > Martin
> >
> 
> 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 [1] to 
> guides and vice versa.
> 
> [1] https://github.com/senchalabs/jsduck/wiki/%40aside

I am not sure to what case the 'bad' and 'have to remove' comemnts apply
to here, can you be more explicit ?

Simo.

-- 
Simo Sorce * Red Hat, Inc * New York