On 09/13/2013 09:12 AM, Simo Sorce wrote: > On Fri, 2013-09-13 at 13:54 +0200, Petr Vobornik wrote: >> On 09/12/2013 09: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 ? >> jsduck, yuidoc, jsdoc and doxygen use some flavor of javadoc. They are >> not compatible though. With regular expressions, existing comments can >> be easily converted ie. into yuidoc. But it would still require some >> additional work because jsduck leverages code introspection, but most of >> the others doesn't so one would have to add the missing information. >> >>> 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. >>> >> It's not just list of members. Added values (general and some jsduck >> specific): >> >> - list of classes grouped by usage (main page) >> - list of events which might not be regular member (just a documented one) >> - descriptions for functions and properties where purpose is not clear >> from their name >> - examples of usage for some classes/members >> - inheritance chain parent class, mixin classes, subclasses >> - info about which parent's method was overridden by a method >> - search (classes, members; doesn't require server side) >> - filter by member name >> - filter by member type: deprecated/protected/public/inherited >> - guides where you can write: 'classname.membername' and it will >> automatically make you a link do relevant doc >> Doc build checks: >> - check if documented type is declared >> - check if member has description >> - check if annotation has correct format >> - check if member belongs to declared class >> - check if overriden member exists >> - duplicate members, params >> >> Not sure if I should elaborate more on usecases (experiences devel vs >> web ui newbie, ...). > Well my concern remains that if we want to change later it will take > some effort, but I guess it is better to have improved docs now and take > care of the 'ruby' problem later if it becomes an issue. > > I find it amusing we have to use ruby to document javascript though, you > would think javascript is a good enough language to do that :-D > > Simo. > I take this as an ack for JSDuck.
-- Thank you, Dmitri Pal Sr. Engineering Manager for IdM portfolio Red Hat Inc. ------------------------------- Looking to carve out IT costs? www.redhat.com/carveoutcosts/ _______________________________________________ Freeipa-devel mailing list Freeipa-devel@redhat.com https://www.redhat.com/mailman/listinfo/freeipa-devel