Mailinglist Archive: yast-devel (66 mails)

< Previous Next >
Re: [yast-devel] Use YARD as code documentation tool?
On Thu, 27 Jun 2013 10:11:40 +0200
Lukas Ocilka <lukas.ocilka@xxxxxxxx> 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@xxxxxxxxxxxx
To contact the owner, e-mail: yast-devel+owner@xxxxxxxxxxxx

< Previous Next >
List Navigation