Skip to content

cabal haddock overhaul planning ticket #10851

Open
@mpickering

Description

@mpickering

It has come to my attention that the cabal haddock command could do with some work.

Related issues

The first thing to do is to clarify the confusion in the codebase about what --enable-documentation means. At the moment it does two separate things.

  1. Build HTML documentation for a component
  2. Build the component with the -haddock option.

Requiring (1) implies (2) but not vice versa. A package can be built with -haddock, but documentation not generated yet. It is important to decouple these two concepts inside cabal so that a user can express which combination they want to use.

Further to this, the switch which turns on -haddock is not implemented correctly, since ./Setup configure doesn't accept an --enable-documentation option, to indicate that the component should be built with documentation.

Task 1: Implement --enable-documentation as a configure time option for ./Setup.
Task 2: Distinguish between requesting (1) and (2) in cabal-install.


Consider an issue such as #10818, here the user wishes to build documentation with different options to their
normal compilation. In this situation

The configuration step of Cabal should therefore record after the build phase, which artifact will have the suitable information in for generating documentation.

  • This will typically be the normal .hi files, when no extra haddock options are passed.
  • If a user wishes to pass different options when compiling in the "haddock" way, a simple "-fno-code" compilation pass can be performed, to produce specific interfaces for generation.

Task 3: Record in the output of ./Setup configure, which interface file way the

In order to implement task 3, the decision needs to be taken earlier about using -dynamic-too, -haddock etc.

Task 3a: Record in the output of ./Setup configure the build combinations which ./Setup build should use to produce the artifacts.


Running cabal haddock should use the --no-compilation flag from haddock when available, and just read information from an interface file. First cabal haddock runs the build phase, which ensures that the artifact which contains the documentation is available.

The "no-compilation" flag will just read interface files, and mean we can remove much complexity from the command which tries to either guess what build did (now decided by configure), or stop haddock from recompiling modules (provided by --no-compilation).

Task 4: Use --no-compilation for cabal haddock when supported.


Then we consider issues such as #8707, there is a tension about whether when running cabal haddock, you should require documentation for all your dependencies, so that hyperlinks work.

Both uses are valid, but it should be possible to configure this behaviour in the normal global/project/local configuration options.

Task 5: Add a flag to control the transitive behavior of cabal haddock.


Finally, we should make the build graph more fine-grained so that building documentation for packages does not force you to rebuild everything.

A good first step for this would be to separate the .html and haddock index generation from the building of the package. Then you can build a package with -haddock, and later generate the .html from that if you need it.
This will fix well into Task 4.

Task 6: Separate documentation building from package building in the build graph.


Comments on this plan would be welcome from anyone who has opened any of the other ticket!

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions