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

[Martin Kosek]

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 :-)

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