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

[David Waern]

2010/4/9 ViaToR (Alvaro V.) <alvivi at gmail.com>:
> 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.

My main concerns are:

1) Two places containing the API reference.

In your example documentation the API reference is included in one of
the chapters. Wouldn't it be better to just have it in one place - the
Haddock docs?

2) Integration with Haddock docs.

I think it would be best if the pages generated by this system and the
pages generated by Haddock would be integrated as much as possible -
both style wise (sharing CSS, structure, headers, footers, sidebars
etc) and also in terms of hyper linking. Identifiers in your
documentation should go to the Haddock docs. It should feel as if the
Haddock pages are just a part of the whole documentation structure.

3) Configuration

I haven't looked at this yet but I suspect people will not want
another configuration file in their projects. Perhaps you could
propose some kind of Cabal integration instead.

David