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

Thu Sep 12 17:11:11 UTC 2013

On 09/12/2013 03:47 PM, Simo Sorce wrote:
> 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:
>>>>>>
>>>>>> [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

I investigated JS support in doxygen little further and I don't think 
that it would work for us.

The support is provided by js2doxy.pl [1][2] script. This script 
converts JS code into C++ code which is then processes by doxygen. One 
of the requirements is that class members are recognized by assigning 
them into constructor's prototype [3]. We don't use this method of class 
definition at all.

[1] 
http://svn.berlios.de/wsvn/jsunit/trunk/jsunit/util/js2doxy.pl?op=file&rev=0&sc=0
[2] http://www.stack.nl/~dimitri/doxygen/helpers.html#doxfilt_js
[3] http://jsunit.berlios.de/internal.html

> The problem is that ruby is still a fast moving target, and we do not
> want to waste time fighiting it when (not if) it will break and you find
> it just right before a release where you want to build docs.
>
> I really would like to avoid dependencies in Ruby in this project
> completely as long as possible.

I would not propose Ruby for any core part of IPA. This doc generation 
is pretty self contained unless we want to include it the doc package. 
Which I assume we don't. Or do we?

So if ruby breaks we could just generate the doc on any system with 
not-broken(older) ruby and put it on the web. Btw JSDuck is developed 
and used by Sencha, one of the, I would say, enterprise Web App 
components companies. Documentation is a core part of their product so I 
assume that they would fix it as soon as possible.

 From usability perspective jsDuck seems to be the best. At almost the 
same level is YUIdoc but there is similar problem as it requires 
Node.js. Please let us avoid to do compromises on UX part.

>
>>>
>>> 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 ?

I assume that if we would move the guides to doc repo and would like to 
avoid requiring the other repo for build, then we would not be able to 
use the guides in the code doc app. In other words, guides would be 
removed from the output code doc and that is the thing I don't like 
(bad). Keeping the code doc and guides together will allow easier cross 
linking. You can see example of the linkage in ExtJS doc: 
http://docs.sencha.com/extjs/4.2.1/#!/guide/mvc_pt2

>
> Simo.
>
-- 
Petr Vobornik