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

[Dmitri Pal]

On 09/12/2013 03:22 PM, Simo Sorce wrote:
> On Thu, 2013-09-12 at 14:54 -0400, Dmitri Pal wrote:
>> 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.
> the probelm, if I understood it correctly is that each of this systems
> have a different markup language, so switching later would mean also
> changing all the markup language in the code, high churn and lot of
> wasted work. I am assuming you use javadoc with javascript with doxygen,
> what does jsduck uses ?
>
> Or are we trying to generate just lists of functions from the actual
> code ? What is the value if there is no associated description of what
> the function does ?

I think there are comments that he already added that come with
functions that he is trying to extract.

>
> Simo.
>


-- 
Thank you,
Dmitri Pal

Sr. Engineering Manager for IdM portfolio
Red Hat Inc.


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