From: Luiz Vitor Martinez Cardoso Date: 2009-02-02T03:49:15+09:00 Subject: [ruby-core:21720] Re: New documentation system! --0022152d7f4d27404c0461dfd9ed Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: quoted-printable Yehuda, Do you have some kind of example? []'s On Sun, Feb 1, 2009 at 4:07 PM, Yehuda Katz wrote: > One project that has been in the works for a while and shows a lot of > promise is YARD. The maintainer got sick a while back but has now returne= d > and is proceeding full-steam-ahead. > YARD supports structured docs (@param foo) but also allows for > rdoc-style completely unstructured docs if that's your piece of cake. > Personally, I find that I prefer rdoc style in application and structured > style in languages, libraries, and frameworks. > > YARD has its own parser, so it would be a worthy replacement for rdoc. > > -- Yehuda > > 2009/2/1 Luiz Vitor Martinez Cardoso > > People, >> >> Look for that: http://docs.python.org/download.html, try to search some >> functions/methods in "Quick Search" field (example: bisect, urllib, re..= .). >> The search field is missing at ruby, and it's make the job easier. >> >> The layout of the doc core system is another point. We need to improve t= he >> interface, show minus things and be more expressive. >> >> Note that I'm nothing suggesting solutions, just putting the problems on >> the table. If the community shows this demand I'll happy to help improve= it! >> >> >> Regards, >> Luiz Vitor. >> >> >> On Sun, Feb 1, 2009 at 2:42 PM, wrote: >> >>> Quoting Austin Ziegler : >>> >>> On Sun, Feb 1, 2009 at 10:51 AM, Luiz Vitor Martinez Cardoso >>>> wrote: >>>> >>>>> What the Ruby community think about developing a better documentation >>>>> system. Something like Python Documentation? >>>>> >>>> >>>> I'm not familiar with "Python Documentation". What exactly do you mean >>>> by "documentation system" (that is, what do you feel that Ruby >>>> currently offers), and what do you mean by "better" (that is, what do >>>> you feel that Ruby currently lacks). >>>> >>>> -austin >>>> -- >>>> Austin Ziegler * halostatue@gmail.com * http://www.halostatue.ca/ >>>> * austin@halostatue.ca * http://www.halostatue.ca/feed/ >>>> * austin@zieglers.ca >>>> >>>> >>>> >>> I'm not familiar with Python documentation either. And I know we've had >>> this discussion before, but I'm a big fan of "literate programming" and >>> "reproducible research." >>> >>> As a "community member", though, I'd expect changes to the "documentati= on >>> system" to be created the same way everything else here is created -- b= y >>> patches, discussions on mailing lists and in IRC, test-driven and >>> behavior-driven development, etc. So if the original poster has some id= eas, >>> I'd certainly like to see what they are, and how they compare with RDoc= / >>> RI. Anybody can start a project on RubyForge or Github, and some projec= ts >>> are appealing enough that developers will gravitate to them. >>> >>> When I run out of other interesting projects, I might revisit the whole >>> "literate programming in Ruby" concept. But the thing is -- what I want= to >>> do already exists in the R language because some R community members bu= ilt >>> it. So there's little incentive for me to actually create something. :) >>> >>> >>> -- >>> M. Edward (Ed) Borasky >>> >>> I've never met a happy clam. In fact, most of them were pretty steamed. >>> >>> >> >> >> -- >> Regards, >> >> Luiz Vitor Martinez Cardoso >> cel.: (11) 8187-8662 >> blog: rubz.org >> engineer student at maua.br >> >> "Posso nunca chegar a ser o melhor engenheiro do mundo, mas tenha certez= a >> de que eu vou lutar com todas as minhas for=E7as para ser o melhor engen= heiro >> que eu puder ser" >> > > > > -- > Yehuda Katz > Developer | Engine Yard > (ph) 718.877.1325 > --=20 Regards, Luiz Vitor Martinez Cardoso cel.: (11) 8187-8662 blog: rubz.org engineer student at maua.br "Posso nunca chegar a ser o melhor engenheiro do mundo, mas tenha certeza d= e que eu vou lutar com todas as minhas for=E7as para ser o melhor engenheiro = que eu puder ser" --0022152d7f4d27404c0461dfd9ed Content-Type: text/html; charset=ISO-8859-1 Content-Transfer-Encoding: quoted-printable Yehuda,

Do you have some kind of example?

[]'s

On Sun, Feb 1, 2009 at 4:07 PM, Yehuda Katz <wycats@gmail.com>= wrote:
One project that = has been in the works for a while and shows a lot of promise is YARD. The m= aintainer got sick a while back but has now returned and is proceeding full= -steam-ahead.

YARD supports structured docs (@param foo<String>) but= also allows for rdoc-style completely unstructured docs if that's your= piece of cake. Personally, I find that I prefer rdoc style in application = and structured style in languages, libraries, and frameworks.

YARD has its own parser, so it would be a worthy replac= ement for rdoc.

-- Yehuda

2009/2/1 Luiz Vitor Martinez Cardoso <grabber@gmail.com><= /span>

People,

Lo= ok for that: http://docs.python.org/download.html, try to search some functions= /methods in "Quick Search" field (example: bisect, urllib, re...)= . The search field is missing at ruby, and it's make the job easier.
The layout of the doc core system is another point. We need to improve = the interface, show minus things and be more expressive.

Note that I= 'm nothing suggesting solutions, just putting the problems on the table= . If the community shows this demand I'll happy to help improve it!


Regards,
Luiz Vitor.


On Sun, Feb 1, 2009 at 2:42 PM, = <znmeb@cesmail.net> wrote:
Quoting Austin Ziegler <halostatue@gmail.com>:

On Sun, Feb 1, 2009 at 10:51 AM, Luiz Vitor Martinez Cardoso
<grabber@gmail.co= m> wrote:
What the Ruby community think about developing a better documentation
system. Something like Python Documentation?

I'm not familiar with "Python Documentation". What exactly do= you mean
by "documentation system" (that is, what do you feel that Ruby currently offers), and what do you mean by "better" (that is, wha= t do
you feel that Ruby currently lacks).

-austin
--
Austin Ziegler * = halostatue@gmail.com * http://www.halostatue.ca/
              * austin@halostatue.ca * http://www.halostatue.ca/fe= ed/
              * austin@zieglers.ca



I'm not familiar with Python documentation either. And I know we've= had this discussion before, but I'm a big fan of "literate progra= mming" and "reproducible research."

As a "community member", though, I'd expect changes to the &q= uot;documentation system" to be created the same way everything else h= ere is created -- by patches, discussions on mailing lists and in IRC, test= -driven and behavior-driven development, etc. So if the original poster has= some ideas, I'd certainly like to see what they are, and how they comp= are with RDoc / RI. Anybody can start a project on RubyForge or Github, and= some projects are appealing enough that developers will gravitate to them.=

When I run out of other interesting projects, I might revisit the whole &qu= ot;literate programming in Ruby" concept. But the thing is -- what I w= ant to do already exists in the R language because some R community members= built it. So there's little incentive for me to actually create someth= ing. :)


--
M. Edward (Ed) Borasky

I've never met a happy clam. In fact, most of them were pretty steamed.=







-- Yehuda Katz
Developer | Engine Yard
(ph) 718.877.1325



--
Regards,

Luiz V= itor Martinez Cardoso
cel.: (11) 8187-8662
blog: rubz.org
engineer student at ma= ua.br

"Posso nunca chegar a ser o melhor engenheiro do mundo, mas tenha = certeza de que eu vou lutar com todas as minhas for=E7as para ser o melhor = engenheiro que eu puder ser"
--0022152d7f4d27404c0461dfd9ed--