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

[Petr Vobornik]

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


>
> 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
-- 
Petr Vobornik