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

[Simo Sorce]

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 ?

Simo.

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