Re: [Chicken-hackers] Distributed egg repo proposal

[Peter Bex]

On Tue, Mar 15, 2011 at 10:13:48AM -0400, John Gabriele wrote:
> > Python has docstrings, Chicken doesn't.
> 
> Hi Jim,
> 
> The Python package docs at packages.python.org/package-name (and not
> many packages are actually making use of the doc hosting)

You have to ask yourself why they aren't making use of it.
Probably because it's too much hassle or otherwise isn't practical
to use?

> are not
> generally generated from docstrings (though they could be). Folks in
> the Python community often use [Sphinx] to generate html docs from
> [ReST] -formatted text files.
> 
> [Sphinx]: http://sphinx.pocoo.org/
> [ReST]: http://docutils.sourceforge.net/rst.html
> 
> I think Ruby has something similar for docs at rubyforge.

Their rdoc documentation really sucks.  It's one of the worst aspects
of Ruby, IMO.

> Incidentally, Perl's CPAN Search http://search.cpan.org/ is of course
> the one that extracts and generates docs from embedded (POD)
> documentation. It also allows developers to have straight .pod files
> in their package which get rendered as html as well.

This is an entirely different approach.

Please, let's keep the discussion focused on repositories.

Documentation is a whole nother can of worms and we've had several
bikesheds about that.  I think people are generally very happy with
what we have now on the wiki, especially now we have chicken-doc and
chickadee.  It obviously ain't broke, so let's not try to fix it, ok?

Cheers,
Peter
-- 
http://sjamaan.ath.cx
--
"The process of preparing programs for a digital computer
 is especially attractive, not only because it can be economically
 and scientifically rewarding, but also because it can be an aesthetic
 experience much like composing poetry or music."
                                                        -- Donald Knuth