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

[Simo Sorce]

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.

-- 
Simo Sorce * Red Hat, Inc * New York