Smalltalk › Pharo › Pharo Smalltalk Developers

Ideas for HelpSystem

_‹ Previous Topic Next Topic _›

Classic

List

Threaded

11 messages Options

Damien Pollet

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-all-your-ruby-gems-3760.html
)

--
Damien Pollet
type less, do more [ | ] http://people.untyped.org/damien.pollet

Stéphane Ducasse

Re: Ideas for HelpSystem

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-all-your-ruby-gems-3760.html

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
>

Stéphane Ducasse

Re: Ideas for HelpSystem

In reply to this post by 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-all-your-ruby-gems-3760.html
> )
>
> --
> Damien Pollet
> type less, do more [ | ] http://people.untyped.org/damien.pollet
>

laurent laffont

Re: Ideas for HelpSystem

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 <[hidden email]> 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-all-your-ruby-gems-3760.html
> )
>
> --
> Damien Pollet
> type less, do more [ | ] http://people.untyped.org/damien.pollet
>

Stéphane Ducasse

Re: Ideas for HelpSystem

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 <[hidden email]> 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-all-your-ruby-gems-3760.html
> > )
> >
> > --
> > Damien Pollet
> > type less, do more [ | ] http://people.untyped.org/damien.pollet
> >
>
>
>

vonbecmann

Re: Ideas for HelpSystem

here's a similar example

http://soek.goodies.st.s3.amazonaws.com/index.html

Sven Van Caekenberghe

Re: Ideas for HelpSystem

On 11 Dec 2010, at 00:18, Bernardo Ezequiel Contreras wrote:

> here's a similar example
>
> http://soek.goodies.st.s3.amazonaws.com/index.html

Very nice indeed.

Never heard of the Cloudfork project, I am reading now...

Sven

Sean P. DeNigris

Re: Ideas for HelpSystem

Administrator

In reply to this post by 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

Cheers,
Sean

Damien Pollet

Re: Ideas for HelpSystem

In reply to this post by Stéphane Ducasse

On Fri, Dec 10, 2010 at 18:41, Stéphane Ducasse
<[hidden email]> 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

Damien Pollet

Re: Ideas for HelpSystem

In reply to this post by vonbecmann

On Sat, Dec 11, 2010 at 00:18, Bernardo Ezequiel Contreras
<[hidden email]> wrote:
> here's a similar example
>
> http://soek.goodies.st.s3.amazonaws.com/index.html

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

Stéphane Ducasse

Re: Ideas for HelpSystem

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
> <[hidden email]> wrote:
>> here's a similar example
>>
>> http://soek.goodies.st.s3.amazonaws.com/index.html
>
> 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
>