[Pharo-project] Ideas for HelpSystem
Hi all, The Ruby guys have a really nifty tool for code documentation (mainly per-class, per-method etc, but README files are used as well and can serve for tutorials). It's called Yard: http://yardoc.org/ Typically it's used to generate documentation, like javadoc, but it can run as a web server with all the documentation of installed Ruby packages (see http://www.rubyinside.com/the-3-step-guide-to-slick-local-documentation-for-... ) -- Damien Pollet type less, do more [ | ] http://people.untyped.org/damien.pollet
On Dec 10, 2010, at 5:17 PM, Damien Pollet wrote:
Hi all,
The Ruby guys have a really nifty tool for code documentation (mainly per-class, per-method etc, but README files are used as well and can serve for tutorials). It's called Yard: http://yardoc.org/
Typically it's used to generate documentation, like javadoc, but it can run as a web server with all the documentation of installed Ruby packages (see http://www.rubyinside.com/the-3-step-guide-to-slick-local-documentation-for-...
what do you mean by it can run as a web server? you have a system and a server and the docs are generated on the fly?
)
-- Damien Pollet type less, do more [ | ] http://people.untyped.org/damien.pollet
On Fri, Dec 10, 2010 at 18:41, Stéphane Ducasse <stephane.ducasse@inria.fr> wrote:
what do you mean by it can run as a web server? you have a system and a server and the docs are generated on the fly?
yard server --gems launches a webserver (typically webrick, but there are options to run thin or mongrel orâ¦) on localhost, showing documentation for all ruby packages installed. the more standard usage is of course to generate html files with documentation for some package you're developing, like javadoc -- Damien Pollet type less, do more [ | ] http://people.untyped.org/damien.pollet
I would really to have that for pharo. Anybody looking for a small project with a big impact on the community? On Dec 10, 2010, at 5:17 PM, Damien Pollet wrote:
Hi all,
The Ruby guys have a really nifty tool for code documentation (mainly per-class, per-method etc, but README files are used as well and can serve for tutorials). It's called Yard: http://yardoc.org/
Typically it's used to generate documentation, like javadoc, but it can run as a web server with all the documentation of installed Ruby packages (see http://www.rubyinside.com/the-3-step-guide-to-slick-local-documentation-for-... )
-- Damien Pollet type less, do more [ | ] http://people.untyped.org/damien.pollet
A year ago I've done this to learn http://magaloma.seasidehosting.st/ (newbie) code is here http://www.squeaksource.com/SimpleWebDoc.html I won't touch it because I work on other stuff but feel free to try and ask..... Laurent On Fri, Dec 10, 2010 at 6:42 PM, Stéphane Ducasse <stephane.ducasse@inria.fr
wrote:
I would really to have that for pharo. Anybody looking for a small project with a big impact on the community?
On Dec 10, 2010, at 5:17 PM, Damien Pollet wrote:
Hi all,
The Ruby guys have a really nifty tool for code documentation (mainly per-class, per-method etc, but README files are used as well and can serve for tutorials). It's called Yard: http://yardoc.org/
Typically it's used to generate documentation, like javadoc, but it can run as a web server with all the documentation of installed Ruby packages (see http://www.rubyinside.com/the-3-step-guide-to-slick-local-documentation-for-... )
-- Damien Pollet type less, do more [ | ] http://people.untyped.org/damien.pollet
thanks for the pointer On Dec 10, 2010, at 7:40 PM, laurent laffont wrote:
A year ago I've done this to learn http://magaloma.seasidehosting.st/
(newbie) code is here http://www.squeaksource.com/SimpleWebDoc.html
I won't touch it because I work on other stuff but feel free to try and ask.....
Laurent
On Fri, Dec 10, 2010 at 6:42 PM, Stéphane Ducasse <stephane.ducasse@inria.fr> wrote: I would really to have that for pharo. Anybody looking for a small project with a big impact on the community?
On Dec 10, 2010, at 5:17 PM, Damien Pollet wrote:
Hi all,
The Ruby guys have a really nifty tool for code documentation (mainly per-class, per-method etc, but README files are used as well and can serve for tutorials). It's called Yard: http://yardoc.org/
Typically it's used to generate documentation, like javadoc, but it can run as a web server with all the documentation of installed Ruby packages (see http://www.rubyinside.com/the-3-step-guide-to-slick-local-documentation-for-... )
-- Damien Pollet type less, do more [ | ] http://people.untyped.org/damien.pollet
On 11 Dec 2010, at 00:18, Bernardo Ezequiel Contreras wrote:
here's a similar example
Very nice indeed. Never heard of the Cloudfork project, I am reading now... Sven
On Sat, Dec 11, 2010 at 00:18, Bernardo Ezequiel Contreras <vonbecmann@gmail.com> wrote:
here's a similar example
Indeed, but part of my point was the how polished Yard is (both appearance and interaction). It integrates API and manual/tutorial-type documentation. Also it's extensible so a project that defines a DSL can also include a Yard plugin to document that DSL nicely. There's an example with Sinatra on their website. -- Damien Pollet type less, do more [ | ] http://people.untyped.org/damien.pollet
let us start small but steady instead of having the full system only in dream. We should really improve on that level so I will allocate some time on that and integrate less fixes. Stef On Dec 12, 2010, at 6:04 AM, Damien Pollet wrote:
On Sat, Dec 11, 2010 at 00:18, Bernardo Ezequiel Contreras <vonbecmann@gmail.com> wrote:
here's a similar example
Indeed, but part of my point was the how polished Yard is (both appearance and interaction). It integrates API and manual/tutorial-type documentation. Also it's extensible so a project that defines a DSL can also include a Yard plugin to document that DSL nicely. There's an example with Sinatra on their website.
-- Damien Pollet type less, do more [ | ] http://people.untyped.org/damien.pollet
Damien Pollet wrote:
The Ruby guys have a really nifty tool for code documentation
Since we're pushing for total documentation, tools are very important because they create a feedback loop on documentation quantity and quality - if one knows docs will be read, one will be more likely to write them and write them well. Per Dave Thomas (RubyConf 2010 keynote), Ruby's near-total documentation came once ri and rdoc pulled comments directly into docs. Sean -- View this message in context: http://forum.world.st/Ideas-for-HelpSystem-tp3082225p3083622.html Sent from the Pharo Smalltalk mailing list archive at Nabble.com.
participants (6)
-
Bernardo Ezequiel Contreras -
Damien Pollet -
laurent laffont -
Sean P. DeNigris -
Stéphane Ducasse -
Sven Van Caekenberghe