GSoC Project: A Haddock + Pandoc documentation tool

older
Can Haskell enforce the dimension?

ViaToR (Alvaro V.)

8 Apr 2010 8 Apr '10

9:55 p.m.

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-Pan... [4] http://bitbucket.org/viator/doc-example/get/tip.zip

Attachments:

attachment.html (text/html — 2.7 KB)

Show replies by date

Mark Lentczner

8 Apr 8 Apr

10:35 p.m.

On Apr 8, 2010, at 6:55 PM, ViaToR (Alvaro V.) wrote:

...

I just finished writing my GSoC proposal ...

The project is about creating a new documentation tool for Haskell projects,...

I've taken a brief look and this looks lovely. I'm currently deep at work on re-coding the Haddock backend to produce semantic XHTML rather than table-nested HTML. I'm pretty familiar now with the internals of the backends of Haddock and would be happy to help you. General GSoC question: Would this be good time to offer to be a mentor? Do we have too many mentors or would it be useful for me to help out here? If so, do I need to register on the GSoC site today or tomorrow? - Mark Mark Lentczner http://www.ozonehouse.com/mark/ IRC: mtnviewmark

Johan Tibell

9 Apr 9 Apr

1:40 a.m.

New subject: GSoC Project: A Haddock + Pandoc documentation tool

On Fri, Apr 9, 2010 at 4:35 AM, Mark Lentczner wrote:

...

On Apr 8, 2010, at 6:55 PM, ViaToR (Alvaro V.) wrote:

...
I just finished writing my GSoC proposal ...

The project is about creating a new documentation tool for Haskell projects,...

I've taken a brief look and this looks lovely. I'm currently deep at work on re-coding the Haddock backend to produce semantic XHTML rather than table-nested HTML. I'm pretty familiar now with the internals of the backends of Haddock and would be happy to help you.

General GSoC question: Would this be good time to offer to be a mentor? Do we have too many mentors or would it be useful for me to help out here? If so, do I need to register on the GSoC site today or tomorrow?

Yes. Since you know Haddock well and care about the project you should definitely sign up. The student application deadline is today at 19:00 UTC. I think mentors can still join after that deadline (if I read the SoC timeline correctly) but I suggest signing up as a mentor today. During the next few weeks the mentors will decide which projects will get accepted and who will mentor them.

David Waern

8:15 a.m.

New subject: GSoC Project: A Haddock + Pandoc documentation tool

2010/4/9 Johan Tibell :

...

On Fri, Apr 9, 2010 at 4:35 AM, Mark Lentczner wrote:

...
On Apr 8, 2010, at 6:55 PM, ViaToR (Alvaro V.) wrote:

...
I just finished writing my GSoC proposal ...

The project is about creating a new documentation tool for Haskell projects,...

I've taken a brief look and this looks lovely. I'm currently deep at work on re-coding the Haddock backend to produce semantic XHTML rather than table-nested HTML. I'm pretty familiar now with the internals of the backends of Haddock and would be happy to help you.

General GSoC question: Would this be good time to offer to be a mentor? Do we have too many mentors or would it be useful for me to help out here? If so, do I need to register on the GSoC site today or tomorrow?

Yes. Since you know Haddock well and care about the project you should definitely sign up. The student application deadline is today at 19:00 UTC. I think mentors can still join after that deadline (if I read the SoC timeline correctly) but I suggest signing up as a mentor today. During the next few weeks the mentors will decide which projects will get accepted and who will mentor them.

I second this. We don't have too many mentors, and we need someone like you with good knowledge of HTML, CSS and the new Haddock backend to mentor a project like this. David

Simon Hengel

3:48 a.m.

...

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).

So where is the proposal? Is there a ticket on GSoC trac? Cheers, Simon

David Waern

9:03 a.m.

New subject: GSoC Project: A Haddock + Pandoc documentation tool

2010/4/9 ViaToR (Alvaro V.) :

...

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

Alvaro Vilanova Vidal (viator)

10:31 a.m.

New subject: GSoC Project: A Haddock + Pandoc documentation tool

...

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?

The example is just a test of how you could create a full-customizable single document which includes the Haddock reference. Of course, the idea is that you could create documentation without any Haddock render directive (but keeping the cross references) and then, you could enable the attachment Haddock reference in the same document or in another document.

...

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.

I agree, and I tried to represent that in the example (but I created a new css). All the documentation will be rendered by Pandoc so there is no difference between the format of each side. I also think it would be interesting to be able to refer to parts of the documentation from Haddock, but keeping the Haddock format (This is not shown in the example).

...

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.

That would be awesome. I have to see how Cabal handles these files.

David Waern

11:56 a.m.

New subject: GSoC Project: A Haddock + Pandoc documentation tool

2010/4/9 Alvaro Vilanova Vidal (viator) :

...

...
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.

I agree, and I tried to represent that in the example (but I created a new css). All the documentation will be rendered by Pandoc so there is no difference between the format of each side. [...]

If we want /one/ API reference (and not one generated by Pandoc and one generated by Haddock), then I think we need to generate it in XHTML format directly. There is no sensible way to transmit all the semantic information we need to be able to style and layout the different Haskell declaration through the markup languages supported by Pandoc. One can embed HTML but I suspect it's not the right solution. David

David Waern

5:32 p.m.

New subject: GSoC Project: A Haddock + Pandoc documentation tool

2010/4/9 Alvaro Vilanova Vidal (viator) :

...

...
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.

That would be awesome. I have to see how Cabal handles these files.

Here's the relevant Cabal ticket: http://hackage.haskell.org/trac/hackage/ticket/330 David

Evan Laforge

2:12 p.m.

New subject: GSoC Project: A Haddock + Pandoc documentation tool

...

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.

It would be a shame if I had to figure out how to write a cabal file for my project and replace the entire build system, if even possible, just to get a documentation tool working. But if it's like haddock and can be configured just with flags and cabal integration just means cabal calling it for you, then there's no problem.

Kyle Murphy

2:30 p.m.

New subject: GSoC Project: A Haddock + Pandoc documentation tool

Just a FYI, there's currently an ongoing discussion in the web-devel mailing list about the woeful state of documentation in the world of Haskell web development, and Haskell in general. It seems like some good might come of combining these two discussions as they both seem to be heading in a similar direction. At the very least those of us not in both the web-devel and haskell-cafe mailing lists might want to check the other one out. -R. Kyle Murphy -- Curiosity was framed, Ignorance killed the cat. On Fri, Apr 9, 2010 at 14:12, Evan Laforge wrote:

...

...
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.

It would be a shame if I had to figure out how to write a cabal file for my project and replace the entire build system, if even possible, just to get a documentation tool working.

But if it's like haddock and can be configured just with flags and cabal integration just means cabal calling it for you, then there's no problem. _______________________________________________ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe

5522

Age (days ago)

5522

Last active (days ago)

List overview

Download

10 comments

8 participants

participants (8)

Alvaro Vilanova Vidal (viator)
David Waern
Evan Laforge
Johan Tibell
Kyle Murphy
Mark Lentczner
Simon Hengel
ViaToR (Alvaro V.)