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

[Dmitri Pal]

On 09/12/2013 09:14 AM, Simo Sorce wrote:
> On Thu, 2013-09-12 at 07:50 +0200, 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 is only one of the problems.
>
>> 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 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.
>
>> 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
> moving to the doc repo does not solve the problem, really, we are still
> depending on a) ruby for generating docs, b) someone knowing Ruby to fix
> things when they will break.
>
> Simo.
>
It seems that doxygen does not work for JS for us.
So it is node.js vs. ruby vs. no generated docs.
Since we always can get back to "no docs" if things go really wrong I do
not see it as an option here.
I do not like either of the other two alternatives. And I do not know
which one would be best if any.

-- 
Thank you,
Dmitri Pal

Sr. Engineering Manager for IdM portfolio
Red Hat Inc.


-------------------------------
Looking to carve out IT costs?
www.redhat.com/carveoutcosts/