On Thu, Apr 4, 2013 at 11:22 PM, Kim-Ee Yeoh <k...@atamo.com> wrote:
> On Fri, Apr 5, 2013 at 3:04 AM, Simon Heath <icefo...@gmail.com> wrote:
> > I humbly suggest reStructuredText rather than Markdown, which is what
> > is used by the Python community for documentation. Since it's
> specifically
> > made for documentation it may be nicer. But, I don't want to spark
> > a format argument.
>
> Could you say something about /why/ you make the suggestion? I, for
> one, would be happy to google and read links, but what's missing from
> that experience would be input from a fellow haskeller. In context. In
> real-time. On topic.
>
> -- Kim-Ee
>
> _______________________________________________
> Haskell-Cafe mailing list
> Haskell-Cafe@haskell.org
> http://www.haskell.org/mailman/listinfo/haskell-cafe
>
I'd actually like to say that Python has great "documentation traditions"
not just thanks to adoption of reStructuredText format, but a bit more. The
greatest thing is an adoption of Sphinx [1] documentation engine. In Sphinx
you write in extended (by special extensions) reStructuredText format,
which is able to easily link to function definitions (with
:func:`foo.bar.baz` or :class:`foo.bar.Baz`), other documents (with
:doc:`other/doc`) and (most importantly) has extension called "autodoc"
which goes and generates documentation for classes and functions
automatically (by gathering it from docstrings and other things, similar to
haddoc, if I'm not mistaken).
My main point is that thanks to adoption of "mixed documentation"
techinique people usually tend to keep documentation with has these
properties:
- it's up to date
- there's (most of the time) no need to keep separate API and non-API
documentation
- API documentation can be easily be extended with long introduction
without having to write it in source code (you can write it in document and
then include autodoc)
I think Haskell's documentation would greatly benefit from (possible?)
adoption of something like Sphinx, but I don't think it supports Haskell
currently.
[1]: http://sphinx.pocoo.org
_______________________________________________
Haskell-Cafe mailing list
Haskell-Cafe@haskell.org
http://www.haskell.org/mailman/listinfo/haskell-cafe
