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 _______________________________________________ Freeipa-devel mailing list Freeipa-devel@redhat.com https://www.redhat.com/mailman/listinfo/freeipa-devel