Re: [openstack-dev] [horizon] JavaScript docs?
On 02/05/2015 06:20 PM, Matthew Farina wrote: > I'd like to step back for a moment as to the purpose of different kinds > of documentation. Sphinx is great and it provides some forms of > documentation. But, why do we document methods, classes, or functions in > python? Should we drop that and rely on Sphinx? I don't think anyone > would argue for that. We actually rely on Sphinx for documenting methods, classes or functions. Not sure what your point is here. -- Radomir Dopieralski __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [horizon] JavaScript docs?
On 02/05/2015 07:26 PM, Michael Krotscheck wrote: > On Thu Feb 05 2015 at 12:07:01 AM Radomir Dopieralski > mailto:openst...@sheep.art.pl>> wrote: > > > Plus, the documentation generator that we are using already, Sphinx, > supports JavaScript perfectly fine, so I see no reason to add > another tool. > > > Try to empathize with us a little here. What you're asking is equivalent > to saying "OpenStack should use JavaDoc for all its documentation > because it supports python". For all the reasons that you would mistrust > JavaDoc, I mistrust Sphinx when it comes to parsing javascript. > > With that in mind, how about we run a side-by-side comparison of Sphinx > vs. NGDoc? Without actual comparable output, this discussion isn't much > more than warring opinions. I'm not mistrusting JavaDoc or NGDoc or whatever new documentation system you are proposing. I merely think that, while JavaScript programmers are special snowflakes indeed, they are not special enough warrant introducing and maintaining a whole separate documentation system, especially since we are already using a documentation system that is well used and maintained by the whole of OpenStack, not just the Python programmers in Horizon. And since you will have to learn to use Sphinx sooner or later anyways, because basically everything in OpenStack is documented using it, I see no reason why we should expend additional energy on implementing, deploying and maintaining a new set of tools, just because you don't like the current one. If it was JavaDoc instead of Sphinx being used by the whole of OpenStack, I would advocate its use the same way as I advocate Sphinx now. It seems that the whole docs format discussion is just a way of putting away having to actually write the docs. -- Radomir Dopieralski __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [horizon] JavaScript docs?
I agree with points made by both Matt and Radomir. We have guidelines for documenting code. Any code. (* I need to go see what our guidelines actually say) But the goal is to have comments that are useful and make the code easier to understand, follow and use. Comments should focus on "what and why" vs "how".Some files are trivial, but I always appreciated having file level comments describing the purpose of this file. Then having method level comments for non-trivial methods, and so forth down to code blocks. This is how projects I have worked on in the past have commented so fellow team members could pick up the code and quickly get caught up to speed and contribute by just reading the code. Now that I am done rambling on comment content As far as structure it would be nice to follow convention and use JSDoc or ngDoc for JavaScript files. Aaron D. Sahlin IBMUSM07(asahlin) Dept. X2WA Phone 507-253-7349 Tie 553-7349 From: Matthew Farina To: "OpenStack Development Mailing List (not for usage questions)" Date: 02/05/2015 11:29 AM Subject: Re: [openstack-dev] [horizon] JavaScript docs? I'd like to step back for a moment as to the purpose of different kinds of documentation. Sphinx is great and it provides some forms of documentation. But, why do we document methods, classes, or functions in python? Should we drop that and rely on Sphinx? I don't think anyone would argue for that. Some documentation has a different purpose. For example, text editors and IDEs can introspect comments and help as we're writing the code. Or, say you have a bit of bit of code like the reusable wizard being written JavaScript. If someone is going to use it there should be a code comment about it. Just like you'd have for the tables class in Python because people are going to use it. JavaScript is a programming language just as much as Python is. If we should have comments in Python we should have comments in JavaScript. It's no different. JSDoc is the common format for JavaScript. It will help with text editors and IDEs. If we are going to move into an API docs site (which we don't have now) using ngDoc would be helpful. I think documenting in a useful manner is a different piece of scope from using that documentation to generate a site. Ideally, we would document JavaScript in a useful manner no matter if we are creating html docs from it or not. To document in a useful manner we should likely use JSDoc (or ngDoc) for the useful tools rather than do it our own way. We should use the wheel everyone else is using rather than do it our own way. Just my 2 cents. On Thu, Feb 5, 2015 at 1:56 AM, Pavel Karikh wrote: On 02/05/2015 11:04 AM, Radomir Dopieralski wrote: > Plus, the documentation generator that we are using already, Sphinx, > supports JavaScript perfectly fine, so I see no reason to add another tool. I agree with Radomir, why we can't just use Sphinx? __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [horizon] JavaScript docs?
On 2015-02-05 10:19:39 -0800 (-0800), Matthew Farina wrote: [...] > Can we have that system parse and use JSDoc? I'd like it to be > useful to both JS devs and the doc generation toolchain. A quick Web search turned up https://github.com/debrouwere/jsdoc-for-sphinx and https://github.com/juhamust/jsdoc-toolkit-rst-template but no doubt there are more. -- Jeremy Stanley __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [horizon] JavaScript docs?
On Thu Feb 05 2015 at 12:07:01 AM Radomir Dopieralski < openst...@sheep.art.pl> wrote: > > Plus, the documentation generator that we are using already, Sphinx, > supports JavaScript perfectly fine, so I see no reason to add another tool. > Try to empathize with us a little here. What you're asking is equivalent to saying "OpenStack should use JavaDoc for all its documentation because it supports python". For all the reasons that you would mistrust JavaDoc, I mistrust Sphinx when it comes to parsing javascript. With that in mind, how about we run a side-by-side comparison of Sphinx vs. NGDoc? Without actual comparable output, this discussion isn't much more than warring opinions. Michael __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [horizon] JavaScript docs?
Ah, I had forgotten about the python module documentation. Sorry about that and thanks for pointing it out. Can we have that system parse and use JSDoc? I'd like it to be useful to both JS devs and the doc generation toolchain. On Thu, Feb 5, 2015 at 9:42 AM, Jeremy Stanley wrote: > On 2015-02-05 09:20:35 -0800 (-0800), Matthew Farina wrote: > [...] > > But, why do we document methods, classes, or functions in python? > > Should we drop that and rely on Sphinx? I don't think anyone would > > argue for that. > [...] > > Particularly since Sphinx collects the method/class/function > docstrings from the source code to assemble them into > documentation[1]. I see that as its primary reason for existing in > fact. Why do you seem to think those choices are at odds with one > another? > > [1] http://docs.openstack.org/developer/nova/api/nova.api.validator.html > -- > Jeremy Stanley > > __ > OpenStack Development Mailing List (not for usage questions) > Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev > __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [horizon] JavaScript docs?
On 2015-02-05 09:20:35 -0800 (-0800), Matthew Farina wrote: [...] > But, why do we document methods, classes, or functions in python? > Should we drop that and rely on Sphinx? I don't think anyone would > argue for that. [...] Particularly since Sphinx collects the method/class/function docstrings from the source code to assemble them into documentation[1]. I see that as its primary reason for existing in fact. Why do you seem to think those choices are at odds with one another? [1] http://docs.openstack.org/developer/nova/api/nova.api.validator.html -- Jeremy Stanley __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [horizon] JavaScript docs?
I'd like to step back for a moment as to the purpose of different kinds of documentation. Sphinx is great and it provides some forms of documentation. But, why do we document methods, classes, or functions in python? Should we drop that and rely on Sphinx? I don't think anyone would argue for that. Some documentation has a different purpose. For example, text editors and IDEs can introspect comments and help as we're writing the code. Or, say you have a bit of bit of code like the reusable wizard being written JavaScript. If someone is going to use it there should be a code comment about it. Just like you'd have for the tables class in Python because people are going to use it. JavaScript is a programming language just as much as Python is. If we should have comments in Python we should have comments in JavaScript. It's no different. JSDoc is the common format for JavaScript. It will help with text editors and IDEs. If we are going to move into an API docs site (which we don't have now) using ngDoc would be helpful. I think documenting in a useful manner is a different piece of scope from using that documentation to generate a site. Ideally, we would document JavaScript in a useful manner no matter if we are creating html docs from it or not. To document in a useful manner we should likely use JSDoc (or ngDoc) for the useful tools rather than do it our own way. We should use the wheel everyone else is using rather than do it our own way. Just my 2 cents. On Thu, Feb 5, 2015 at 1:56 AM, Pavel Karikh wrote: > On 02/05/2015 11:04 AM, Radomir Dopieralski wrote: > > Plus, the documentation generator that we are using already, Sphinx, > > supports JavaScript perfectly fine, so I see no reason to add another > tool. > > I agree with Radomir, why we can't just use Sphinx? > > __ > OpenStack Development Mailing List (not for usage questions) > Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev > > __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [horizon] JavaScript docs?
On 02/05/2015 11:04 AM, Radomir Dopieralski wrote: > Plus, the documentation generator that we are using already, Sphinx, > supports JavaScript perfectly fine, so I see no reason to add another tool. I agree with Radomir, why we can't just use Sphinx? __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [horizon] JavaScript docs?
On 02/05/2015 10:27 AM, Anton Zemlyanov wrote: > JSDoc (ngdoc) is good thing. It allows to describe files, functions and > it's parameters, constructors, classes in case of ES6. As does Sphinx. > The problem is it tends to diverge with reality. The code is being fixed > and evolved, but comments are often not updated (who want to do much > more work)? And JSDoc generated documentation loses the connection to > reality. That is not a problem. We will just reject patches that do such changes without updating the comments. -- Radomir Dopieralski __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [horizon] JavaScript docs?
JSDoc (ngdoc) is good thing. It allows to describe files, functions and it's parameters, constructors, classes in case of ES6. The problem is it tends to diverge with reality. The code is being fixed and evolved, but comments are often not updated (who want to do much more work)? And JSDoc generated documentation loses the connection to reality. Anton On Thu, Feb 5, 2015 at 12:04 PM, Radomir Dopieralski wrote: > On 02/04/2015 06:06 PM, Thai Q Tran wrote: > > As we're moving toward Angular, might make sense for us to adopt ngdoc > > as well. > > I don't think it makes much sense. We don't have any style guide for the > JavaScript documentation simply because it's not needed. We don't really > have any for Python either (although there might be a lot of > python-specific stuff in what we have). We just have guidelines for > documenting code. Any code. JavaScript, Python, even templates. > > Plus, the documentation generator that we are using already, Sphinx, > supports JavaScript perfectly fine, so I see no reason to add another tool. > > I agree it would be nice to actually start using it for JavaScript code > too, though. > > -- > Radomir Dopieralski > > > __ > OpenStack Development Mailing List (not for usage questions) > Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev > __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [horizon] JavaScript docs?
On 02/04/2015 06:06 PM, Thai Q Tran wrote: > As we're moving toward Angular, might make sense for us to adopt ngdoc > as well. I don't think it makes much sense. We don't have any style guide for the JavaScript documentation simply because it's not needed. We don't really have any for Python either (although there might be a lot of python-specific stuff in what we have). We just have guidelines for documenting code. Any code. JavaScript, Python, even templates. Plus, the documentation generator that we are using already, Sphinx, supports JavaScript perfectly fine, so I see no reason to add another tool. I agree it would be nice to actually start using it for JavaScript code too, though. -- Radomir Dopieralski __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [horizon] JavaScript docs?
I'd recommend taking a look at the dgeni project which is a formal breakout of the code that supports ngdoc into a usable library. https://github.com/angular/dgeni Eric - Original Message - > From: "Monty Taylor" > To: openstack-dev@lists.openstack.org > Sent: Wednesday, February 4, 2015 4:00:17 PM > Subject: Re: [openstack-dev] [horizon] JavaScript docs? > > On 02/04/2015 12:48 PM, Michael Krotscheck wrote: > > I agree. StoryBoard's storyboard-webclient project has a lot of existing > > code already that's pretty well documented, but without knowing what > > documentation system we were going to settle on we never put any rule > > enforcement in place. If someone wants to take a stab at putting together a > > javascript docs build, that project would provide a good test bed that will > > let you test out the tools without having to also make them dance with > > python/sphinx at the same time. > > > > I.E. I have a bunch of javascript that you can hack on, and the domain > > knowledge of the Infra JS Build tools. I'd be happy to support this effort. > > +100 > > > Michael > > > > On Wed Feb 04 2015 at 9:09:22 AM Thai Q Tran wrote: > > > >> As we're moving toward Angular, might make sense for us to adopt ngdoc as > >> well. > >> > >> -Matthew Farina wrote: - > >> To: "OpenStack Development Mailing List (not for usage questions)" < > >> openstack-dev@lists.openstack.org> > >> From: Matthew Farina > >> Date: 02/04/2015 05:42AM > >> Subject: [openstack-dev] [horizon] JavaScript docs? > >> > >> > >> In python we have a style to document methods, classes, and so forth. But, > >> I don't see any guidance on how JavaScript should be documented. I was > >> looking for something like jsdoc or ngdoc (an extension of jsdoc). Is > >> there > >> any guidance on how JavaScript should be documented? > >> > >> For anyone who doesn't know, Angular uses ngdoc (an extension to the > >> commonly used jsdoc) which is written up at > >> https://github.com/angular/angular.js/wiki/Writing-AngularJS-Documentation > >> . > >> __ > >> OpenStack Development Mailing List (not for usage questions) > >> Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe > >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev > >> __ > >> OpenStack Development Mailing List (not for usage questions) > >> Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe > >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev > >> > > > > > > > > __ > > OpenStack Development Mailing List (not for usage questions) > > Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe > > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev > > > > > __ > OpenStack Development Mailing List (not for usage questions) > Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev > __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [horizon] JavaScript docs?
On 02/04/2015 12:48 PM, Michael Krotscheck wrote: > I agree. StoryBoard's storyboard-webclient project has a lot of existing > code already that's pretty well documented, but without knowing what > documentation system we were going to settle on we never put any rule > enforcement in place. If someone wants to take a stab at putting together a > javascript docs build, that project would provide a good test bed that will > let you test out the tools without having to also make them dance with > python/sphinx at the same time. > > I.E. I have a bunch of javascript that you can hack on, and the domain > knowledge of the Infra JS Build tools. I'd be happy to support this effort. +100 > Michael > > On Wed Feb 04 2015 at 9:09:22 AM Thai Q Tran wrote: > >> As we're moving toward Angular, might make sense for us to adopt ngdoc as >> well. >> >> -Matthew Farina wrote: - >> To: "OpenStack Development Mailing List (not for usage questions)" < >> openstack-dev@lists.openstack.org> >> From: Matthew Farina >> Date: 02/04/2015 05:42AM >> Subject: [openstack-dev] [horizon] JavaScript docs? >> >> >> In python we have a style to document methods, classes, and so forth. But, >> I don't see any guidance on how JavaScript should be documented. I was >> looking for something like jsdoc or ngdoc (an extension of jsdoc). Is there >> any guidance on how JavaScript should be documented? >> >> For anyone who doesn't know, Angular uses ngdoc (an extension to the >> commonly used jsdoc) which is written up at >> https://github.com/angular/angular.js/wiki/Writing-AngularJS-Documentation >> . >> __ >> OpenStack Development Mailing List (not for usage questions) >> Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev >> __ >> OpenStack Development Mailing List (not for usage questions) >> Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev >> > > > > __ > OpenStack Development Mailing List (not for usage questions) > Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev > __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [horizon] JavaScript docs?
I agree. StoryBoard's storyboard-webclient project has a lot of existing code already that's pretty well documented, but without knowing what documentation system we were going to settle on we never put any rule enforcement in place. If someone wants to take a stab at putting together a javascript docs build, that project would provide a good test bed that will let you test out the tools without having to also make them dance with python/sphinx at the same time. I.E. I have a bunch of javascript that you can hack on, and the domain knowledge of the Infra JS Build tools. I'd be happy to support this effort. Michael On Wed Feb 04 2015 at 9:09:22 AM Thai Q Tran wrote: > As we're moving toward Angular, might make sense for us to adopt ngdoc as > well. > > -Matthew Farina wrote: - > To: "OpenStack Development Mailing List (not for usage questions)" < > openstack-dev@lists.openstack.org> > From: Matthew Farina > Date: 02/04/2015 05:42AM > Subject: [openstack-dev] [horizon] JavaScript docs? > > > In python we have a style to document methods, classes, and so forth. But, > I don't see any guidance on how JavaScript should be documented. I was > looking for something like jsdoc or ngdoc (an extension of jsdoc). Is there > any guidance on how JavaScript should be documented? > > For anyone who doesn't know, Angular uses ngdoc (an extension to the > commonly used jsdoc) which is written up at > https://github.com/angular/angular.js/wiki/Writing-AngularJS-Documentation > . > __ > OpenStack Development Mailing List (not for usage questions) > Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev > __ > OpenStack Development Mailing List (not for usage questions) > Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev > __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [horizon] JavaScript docs?
As we're moving toward Angular, might make sense for us to adopt ngdoc as well.-Matthew Farina wrote: -To: "OpenStack Development Mailing List (not for usage questions)" From: Matthew Farina Date: 02/04/2015 05:42AMSubject: [openstack-dev] [horizon] _javascript_ docs?In python we have a style to document methods, classes, and so forth. But, I don't see any guidance on how _javascript_ should be documented. I was looking for something like jsdoc or ngdoc (an extension of jsdoc). Is there any guidance on how _javascript_ should be documented?For anyone who doesn't know, Angular uses ngdoc (an extension to the commonly used jsdoc) which is written up at https://github.com/angular/angular.js/wiki/Writing-AngularJS-Documentation. __OpenStack Development Mailing List (not for usage questions)Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribehttp://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
[openstack-dev] [horizon] JavaScript docs?
In python we have a style to document methods, classes, and so forth. But, I don't see any guidance on how JavaScript should be documented. I was looking for something like jsdoc or ngdoc (an extension of jsdoc). Is there any guidance on how JavaScript should be documented? For anyone who doesn't know, Angular uses ngdoc (an extension to the commonly used jsdoc) which is written up at https://github.com/angular/angular.js/wiki/Writing-AngularJS-Documentation. __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
