[Haskell-cafe] GSoC Project: A Haddock + Pandoc documentation tool

ViaToR (Alvaro V.) alvivi at gmail.com
Thu Apr 8 21:55:03 EDT 2010


Hello,

I just finished writing my GSoC proposal and I want to have some feedback
from the community. I'll try to be brief (this is not the proposal).

The project is about creating a new documentation tool for Haskell projects,
like Sphinx[1] for Python or Scribble[2] for Scheme. We have Haddock, which
is a great tool. It can take the sources of a project and generate a useful
API reference. But the reference is just a fragment of the whole project
documentation. So, Haddock can only do a part of what Sphinx can do. But we
have another tool, Pandoc, that takes files of whatever markup language and
transform it to another format. And this is the more general-purposed part
of Sphinx that is missing in Haddock. So we have the tools for creating
documentation as useful as other systems, we just need the glue and several
improvements.

To achieve this project, first I'll have to use Haddock as an API.
Currently, the Haddock API is rudimentary and highly experimental, so I
would have to extend and test it. Then I would have to write a Haddock
backend which would generate the reference in an internal independent pandoc
format [3]. Finally I would have to write a new command-line program that
would manage the projects or I would have to add Pandoc support in Haddock
command-line program or Haddock support in Pandoc. IMHO, I think that will
be better a new command-line program, everyone with its own purpose.

I created an example of what would be a library documented with this system
[4]. The file contains a configuration file a la cabal, a reST file (It
could be markdown) and the html output. I tried to represent that the html
output for the reference have to be almost the same  that generates Haddock
(css may differ). Note that all the entries of the Haddock reference are
first-citizens entities in the documentation, so you can refer to the
entries, render one entry, all or by groups (there are examples in the reST
file).

I am looking forward your impressions and suggestions.
Thanks to Simon Marlow, David Waern and Conal Elliott for their suggestions
and help. Thanks you all.

[1] http://sphinx.pocoo.org/
[2] http://docs.plt-scheme.org/scribble/
[3]
http://hackage.haskell.org/packages/archive/pandoc/1.5.1.1/doc/html/Text-Pandoc-Definition.html#t%3APandoc
[4] http://bitbucket.org/viator/doc-example/get/tip.zip
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://www.haskell.org/pipermail/haskell-cafe/attachments/20100408/09abf293/attachment.html


More information about the Haskell-Cafe mailing list