Re: [Freeipa-devel] [PATCH] 451-458 Web UI devel and source code documentation
On 10/15/2013 03:30 PM, Ana Krivokapic wrote: On 10/02/2013 02:20 PM, Petr Vobornik wrote: On 09/16/2013 05:24 PM, Ana Krivokapic wrote: On 09/11/2013 12:44 PM, Petr Vobornik wrote: Hello, snip I looked into the documentation effort and (ruby dependency discussion aside) I don't have any major objections. I like how the generated pages look, and they are intuitive and easy to navigate. A couple of nitpicks: 1) There are some spelling mistakes (e.g. Apllication_controller) Fixed 2) Bulleted lists are not rendered nicely in the html output (see for example the doc string for _base.Builder property 'string_mode'. I think a list needs to look like this in the source code: /** * This is a list: * * - 'element1' * - 'element2' * */ as opposed to this: /** * This is a list: * - 'element1' * - 'element2' */ Fixed on many places. Also fixed the same issue in some code examples. - _base.Builder doc was heavily revised - added doc comments to ./plugin_loader All patches are rebased but just patches 452 and 453 are changed. Looks good, ACK. Pushed to master -- Petr Vobornik ___ Freeipa-devel mailing list Freeipa-devel@redhat.com https://www.redhat.com/mailman/listinfo/freeipa-devel
Re: [Freeipa-devel] [PATCH] 451-458 Web UI devel and source code documentation
On 10/02/2013 02:20 PM, Petr Vobornik wrote: On 09/16/2013 05:24 PM, Ana Krivokapic wrote: On 09/11/2013 12:44 PM, Petr Vobornik wrote: Hello, snip I looked into the documentation effort and (ruby dependency discussion aside) I don't have any major objections. I like how the generated pages look, and they are intuitive and easy to navigate. A couple of nitpicks: 1) There are some spelling mistakes (e.g. Apllication_controller) Fixed 2) Bulleted lists are not rendered nicely in the html output (see for example the doc string for _base.Builder property 'string_mode'. I think a list needs to look like this in the source code: /** * This is a list: * * - 'element1' * - 'element2' * */ as opposed to this: /** * This is a list: * - 'element1' * - 'element2' */ Fixed on many places. Also fixed the same issue in some code examples. - _base.Builder doc was heavily revised - added doc comments to ./plugin_loader All patches are rebased but just patches 452 and 453 are changed. Looks good, ACK. -- Regards, Ana Krivokapic Associate Software Engineer FreeIPA team Red Hat Inc. ___ Freeipa-devel mailing list Freeipa-devel@redhat.com https://www.redhat.com/mailman/listinfo/freeipa-devel
Re: [Freeipa-devel] [PATCH] 451-458 Web UI devel and source code documentation
On 09/13/2013 08:31 PM, Dmitri Pal wrote: On 09/13/2013 09:12 AM, Simo Sorce wrote: On Fri, 2013-09-13 at 13:54 +0200, Petr Vobornik wrote: ... 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. Right. Until we find that using ruby is indeed a blocker or until we find some way to get rid of ruby without degrading Web UI docs quality... Martin ___ Freeipa-devel mailing list Freeipa-devel@redhat.com https://www.redhat.com/mailman/listinfo/freeipa-devel
Re: [Freeipa-devel] [PATCH] 451-458 Web UI devel and source code documentation
On 09/11/2013 12:44 PM, 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 ___ Freeipa-devel mailing list Freeipa-devel@redhat.com https://www.redhat.com/mailman/listinfo/freeipa-devel I looked into the documentation effort and (ruby dependency discussion aside) I don't have any major objections. I like how the generated pages look, and they are intuitive and easy to navigate. A couple of nitpicks: 1) There are some spelling mistakes (e.g. Apllication_controller) 2) Bulleted lists are not rendered nicely in the html output (see for example the doc string for _base.Builder property 'string_mode'. I think a list needs to look like this in the source code: /** * This is a list: * * - 'element1' * - 'element2' * */ as opposed to this: /** * This is a list: * - 'element1' * - 'element2' */ -- Regards, Ana Krivokapic Associate Software Engineer FreeIPA team Red Hat Inc. ___ Freeipa-devel mailing list Freeipa-devel@redhat.com https://www.redhat.com/mailman/listinfo/freeipa-devel
Re: [Freeipa-devel] [PATCH] 451-458 Web UI devel and source code documentation
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
Re: [Freeipa-devel] [PATCH] 451-458 Web UI devel and source code documentation
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 -
Re: [Freeipa-devel] [PATCH] 451-458 Web UI devel and source code documentation
On 09/12/2013 07:50 AM, 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 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 question is if we want to include these docs into some freeipa-doc package. I don't think it's necessary. The important thing is to have it on the web. Short overview of other JavaScript doc tools JSDoc https://github.com/jsdoc3/jsdoc http://usejsdoc.org/ - runs on rhino or can be downloaded by npm - doc comments need to be too verbose (problems with introspection of old class system) - output is much worse then jsduck (can't find online example, the one which I generated is already gone) - slow ScriptDoc/AjaxDoc http://ajaxdoc.codeplex.com/ - requires .NET YUIDoc http://developer.yahoo.com/yui/yuidoc/ - requires node.js + nice output http://yuilibrary.com/yui/docs/api/classes/Graph.html - doesn't do code introspection - every information has to be in doc comment NaturalDocs http://www.naturaldocs.org/ + packaged - only basic JavaScript support (no code introspection) - don't like the output http://people.apache.org/~jkuhnert/ Doxygen + packaged (not sure about JS support) - the output is pretty bad http://jsunit.berlios.de/classes.html Dojo Doc - output requires php + nice output https://dojotoolkit.org/api/ ~ not sure about code introspection, most likely works only with Dojo classes JSDuck - ruby + IMO best output + sufficient code introspection - Works with older and new code + fast (compare to JSDoc) Subjective comparison in specific areas: - Writing doc comments: JSDuck YUIDoc | DojoDoc | NaturalDocs JSDoc Doxygen - Output (UX) JSDuck YUIDoc | DojoDoc NaturalDocs JSDoc Doxygen - Packaging NaturalDocs | Doxygen JSDuck | YUIDoc JSDoc DojoDoc 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 Martin The move can be considered only if we want to package the code doc. And we might then require freeipa repo for doc generation which is not good. To avoid it we would have to remove guides from the output app. It's bad because it would break or make more difficult links from code [1] to guides and vice versa. [1] https://github.com/senchalabs/jsduck/wiki/%40aside -- Petr Vobornik ___ Freeipa-devel mailing list Freeipa-devel@redhat.com https://www.redhat.com/mailman/listinfo/freeipa-devel
Re: [Freeipa-devel] [PATCH] 451-458 Web UI devel and source code documentation
On Thu, 2013-09-12 at 11:02 +0200, Petr Vobornik wrote: On 09/12/2013 07:50 AM, 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 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 question is if we want to include these docs into some freeipa-doc package. I don't think it's necessary. The important thing is to have it on the web. Short overview of other JavaScript doc tools JSDoc https://github.com/jsdoc3/jsdoc http://usejsdoc.org/ - runs on rhino or can be downloaded by npm - doc comments need to be too verbose (problems with introspection of old class system) - output is much worse then jsduck (can't find online example, the one which I generated is already gone) - slow ScriptDoc/AjaxDoc http://ajaxdoc.codeplex.com/ - requires .NET YUIDoc http://developer.yahoo.com/yui/yuidoc/ - requires node.js + nice output http://yuilibrary.com/yui/docs/api/classes/Graph.html - doesn't do code introspection - every information has to be in doc comment NaturalDocs http://www.naturaldocs.org/ + packaged - only basic JavaScript support (no code introspection) - don't like the output http://people.apache.org/~jkuhnert/ Doxygen + packaged (not sure about JS support) - the output is pretty bad http://jsunit.berlios.de/classes.html Dojo Doc - output requires php + nice output https://dojotoolkit.org/api/ ~ not sure about code introspection, most likely works only with Dojo classes JSDuck - ruby + IMO best output + sufficient code introspection - Works with older and new code + fast (compare to JSDoc) Subjective comparison in specific areas: - Writing doc comments: JSDuck YUIDoc | DojoDoc | NaturalDocs JSDoc Doxygen - Output (UX) JSDuck YUIDoc | DojoDoc NaturalDocs JSDoc Doxygen - Packaging NaturalDocs | Doxygen JSDuck | YUIDoc JSDoc DojoDoc To be honest, I would go with the old and tried doxygen, maybe we can find a way to make the output not look too bad ? The output you link up there is the worst thing I have ever seen, but it is not what I have seen in most other doxygen generated outputs. This one doesn't look bad: https://talloc.samba.org/talloc/doc/html/group__talloc__ref.html This is also generated by doxygen and looks ok to me: http://dbus.freedesktop.org/doc/api/html/index.html 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 Martin The move can be considered only if we want to package the code doc. And we might then require freeipa repo for doc generation which is not good. To avoid it we would have to remove guides from the output app. It's bad because it would break or make more difficult links from code [1] to guides and vice versa. [1] https://github.com/senchalabs/jsduck/wiki/%40aside I am not sure to what case the 'bad' and 'have to remove' comemnts apply to here, can you be more explicit ? Simo. -- Simo Sorce * Red
Re: [Freeipa-devel] [PATCH] 451-458 Web UI devel and source code documentation
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. -- 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
Re: [Freeipa-devel] [PATCH] 451-458 Web UI devel and source code documentation
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/ ___ Freeipa-devel mailing list Freeipa-devel@redhat.com https://www.redhat.com/mailman/listinfo/freeipa-devel
Re: [Freeipa-devel] [PATCH] 451-458 Web UI devel and source code documentation
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
Re: [Freeipa-devel] [PATCH] 451-458 Web UI devel and source code documentation
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 ___ Freeipa-devel mailing list Freeipa-devel@redhat.com https://www.redhat.com/mailman/listinfo/freeipa-devel
Re: [Freeipa-devel] [PATCH] 451-458 Web UI devel and source code documentation
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
Re: [Freeipa-devel] [PATCH] 451-458 Web UI devel and source code documentation
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. -- Simo Sorce * Red Hat, Inc * New York ___ Freeipa-devel mailing list Freeipa-devel@redhat.com https://www.redhat.com/mailman/listinfo/freeipa-devel
Re: [Freeipa-devel] [PATCH] 451-458 Web UI devel and source code documentation
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. -- 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
Re: [Freeipa-devel] [PATCH] 451-458 Web UI devel and source code documentation
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 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 :-) 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 Martin ___ Freeipa-devel mailing list Freeipa-devel@redhat.com https://www.redhat.com/mailman/listinfo/freeipa-devel
