[yast-devel] Use YARD as code documentation tool?
Hi, in the YCP Killer project we are currently working on transferring comments from YCP to Ruby. One part of that work is transferring documentation comments. This brings up the question of what documentation tool we want to use for YaST code in Ruby in general. There are two main contenders: * RDoc [1] * YARD [2] RDoc is a used since the very early days of Ruby. It is well known and its is somewhat a standard tool. YARD is a newer, backward compatible with RDoc, but with more capabilities. It generates nicer documentation and its syntax is more similar to the current YaST one (it uses @tags). It can use widespread markup languages (like Markdown) instead of inventing its own wiki-style markup (like RDoc). It is extensible and it allows quick development by running a local server and seeing changes instantly (you just run "yard server --reload" and edit your files). The killer feature of YARD is however the RubyDoc server [3]. There you can find documentation to many Ruby-based projects. You can add your own easily (which basically gives you a documentation hosting for free on a place expected by Ruby community). One great future is integration with GitHub, so you can see documentation of the development version of your project online immediately. Because of all these features, most new Ruby projects choose YARD as their code documentation tool. From the above, I guess it's obvious that I would like Ruby code in YaST to use YARD too. Do you agree with that, or do you have any better ideas? [1] http://rdoc.sourceforge.net/ [2] http://yardoc.org/ [3] http://rubydoc.info/ -- David Majda SUSE Studio developer http://susestudio.com/ -- To unsubscribe, e-mail: yast-devel+unsubscribe@opensuse.org To contact the owner, e-mail: yast-devel+owner@opensuse.org
On 06/27/2013 09:32 AM, David Majda wrote:
Hi,
in the YCP Killer project we are currently working on transferring comments from YCP to Ruby. One part of that work is transferring documentation comments. This brings up the question of what documentation tool we want to use for YaST code in Ruby in general.
There are two main contenders:
* RDoc [1] * YARD [2] ... shortened ...
From the above, I guess it's obvious that I would like Ruby code in YaST to use YARD too. Do you agree with that, or do you have any better ideas?
We already have a hosting [#1] for our documentation because Yast is not just about bultins and libraries. There's plenty of other documentation written in docbook already. On the other hand, "standard" docs place makes sense, and even more after we switch to Ruby. Any idea how we could create a merged documentation from docbook we have and on of the offered ones? BTW, it seems that the current docs haven't been updated for a while! #1 http://doc.opensuse.org/projects/YaST/ Lukas -- Lukas Ocilka, Cloud & Systems Management Department SUSE LINUX s.r.o., Praha -- To unsubscribe, e-mail: yast-devel+unsubscribe@opensuse.org To contact the owner, e-mail: yast-devel+owner@opensuse.org
On Thu, 27 Jun 2013 10:11:40 +0200 Lukas Ocilka <lukas.ocilka@suse.com> wrote:
On 06/27/2013 09:32 AM, David Majda wrote:
Hi,
in the YCP Killer project we are currently working on transferring comments from YCP to Ruby. One part of that work is transferring documentation comments. This brings up the question of what documentation tool we want to use for YaST code in Ruby in general.
There are two main contenders:
* RDoc [1] * YARD [2] ... shortened ...
From the above, I guess it's obvious that I would like Ruby code in YaST to use YARD too. Do you agree with that, or do you have any better ideas?
We already have a hosting [#1] for our documentation because Yast is not just about bultins and libraries. There's plenty of other documentation written in docbook already. On the other hand, "standard" docs place makes sense, and even more after we switch to Ruby.
Any idea how we could create a merged documentation from docbook we have and on of the offered ones?
BTW, it seems that the current docs haven't been updated for a while!
#1 http://doc.opensuse.org/projects/YaST/
Lukas
Well, I think that documentation need to be reviewed if it makes sense, as part of documentation is already obsoleted. And I think we can convert docbook to markdown ( which is in fact easier to write and review! ) - see http://johnmacfarlane.net/pandoc/demos.html (demo number 31 ) And when you have markdown, then you can include it in generated documentation - see http://www.rubydoc.info/github/susestudio/studio_api/frames where initial page is written in markdown. Also you can see markdown immediatelly on github - https://github.com/susestudio/studio_api and you can make it much easier to edit. So from this perspective I think that YARD is good option here for its native support of markdown ( but even rdoc support it ). Also one more point why I think that yardoc is better is that you can have file .yardoc with all settings like custom pages and then just call yardoc on top level directory and it generate documentation, so it is much easier to not repeat code. Josef -- To unsubscribe, e-mail: yast-devel+unsubscribe@opensuse.org To contact the owner, e-mail: yast-devel+owner@opensuse.org
Dne 27.6.2013 10:11, Lukas Ocilka napsal(a):
On 06/27/2013 09:32 AM, David Majda wrote:
From the above, I guess it's obvious that I would like Ruby code in YaST to use YARD too. Do you agree with that, or do you have any better ideas?
We already have a hosting [#1] for our documentation because Yast is not just about bultins and libraries. There's plenty of other documentation written in docbook already. On the other hand, "standard" docs place makes sense, and even more after we switch to Ruby.
What I had in mind was mostly code documentation (documentation of classes, methods, etc.). This doesn't have to be at the same place as other, more general, documentation. It also doesn't have to be generated by the same tool. (Although it can, as Josef suggests in the other e-mail.)
BTW, it seems that the current docs haven't been updated for a while!
Which only underscores that autogenerating may be a good idea :-) -- David Majda SUSE Studio developer http://susestudio.com/ -- To unsubscribe, e-mail: yast-devel+unsubscribe@opensuse.org To contact the owner, e-mail: yast-devel+owner@opensuse.org
On 27/06/13 09:32, David Majda wrote:
* RDoc [1] * YARD [2]
I use YARD for my projects and I am happy with it. I like that you can annotate types ej: @param [Array<String>] names Names to process which makes documentation more clear in a duck world. -- Duncan Mac-Vicar P. - http://www.suse.com/ SUSE LINUX Products GmbH, GF: Jeff Hawn, Jennifer Guild, Felix Imendörffer, HRB 16746 (AG Nürnberg) Maxfeldstraße 5, 90409 Nürnberg, Germany -- To unsubscribe, e-mail: yast-devel+unsubscribe@opensuse.org To contact the owner, e-mail: yast-devel+owner@opensuse.org
participants (4)
-
David Majda -
Duncan Mac-Vicar P. -
Josef Reidinger -
Lukas Ocilka