Haddock doesn't work (with Backpack?)

[int-index]

The HTML documentation is not generated at all. UPD: seems to be caused by #4506

System configuration: Xubuntu, ghc-8.2.2 and cabal-head installed from ppa:hvr/ghc.

Project structure:

backpack-haddock
├── cabal.project
├── cabal.project.local
└── pkg-example
    ├── pkg-example.cabal
    ├── Setup.hs
    └── src
        └── Pkg
            ├── Core.hs
            └── Sig.hsig

File contents:

• cabal.project:

  packages: pkg-example/
  

• cabal.project.local:

  with-compiler: /opt/ghc/8.2.2/bin/ghc
  documentation: True
  

• pkg-example/pkg-example.cabal:

  name: pkg-example
  version: 0
  build-type: Simple
  cabal-version: >=2.0
  
  library
    signatures: Pkg.Sig
    exposed-modules: Pkg.Core
    build-depends: base
    hs-source-dirs: src
    default-language: Haskell2010
    ghc-options: -Wall
  

• pkg-example/Setup.hs:

  import Distribution.Simple
  main = defaultMain
  

• pkg-example/src/Pkg/Sig.hsig:

  -- | An abstract signature
  
  signature Pkg.Sig where
  
  -- | Documented type
  data A
  
  -- | Documented function
  conv :: A -> A
  

• pkg-example/src/Pkg/Core.hs:

  -- | Module description
  
  module Pkg.Core (launchMissiles) where
  
  import Pkg.Sig
  
  -- | Documented function
  launchMissiles :: A -> A
  launchMissiles = conv . conv
  

Steps to reproduce:

$ cabal new-build pkg-example
Resolving dependencies...
Build profile: -w ghc-8.2.2 -O1
In order, the following will be built (use -v for more details):
 - pkg-example-0 (lib) (first run)
Configuring library for pkg-example-0..
Preprocessing library for pkg-example-0..
Building library instantiated with Pkg.Sig = <Pkg.Sig>
for pkg-example-0..
[1 of 2] Compiling Pkg.Sig[sig]     ( src/Pkg/Sig.hsig, nothing )
[2 of 2] Compiling Pkg.Core         ( src/Pkg/Core.hs, nothing )

$ cabal new-haddock pkg-example
Up to date

Expected result: there are HTML files in dist-newstyle.
Actual result: no documentation generated.

[int-index]

Looks like this is not caused by Backpack, see #4506
The problem is that Haddock doesn't detect that there's work to do. I modified pkg-example/src/Pkg/Core.hs and the docs were generated:

$ cabal new-haddock pkg-example
Build profile: -w ghc-8.2.2 -O1
In order, the following will be built (use -v for more details):
 - pkg-example-0 (lib) (file src/Pkg/Core.hs changed)
Preprocessing library for pkg-example-0..
Running Haddock on library instantiated with Pkg.Sig = <Pkg.Sig>
for pkg-example-0..
Haddock coverage:
Warning: Renamed source is not available.
   0% (  0 /  1) in 'Pkg.Sig'
  Missing documentation for:
    Module header
 100% (  2 /  2) in 'Pkg.Core'
Warning: Pkg.Core: could not find link destinations for:
    A
Documentation created:
backpack-haddock/dist-newstyle/build/x86_64-linux/ghc-8.2.2/pkg-example-0/doc/html/pkg-example/index.html

[int-index]

The docs for the signature are empty, though:

[int-index]

I tried to use the same technique (modifying the file before cabal new-haddock) in https://github.com/int-index/slay and got the following error:

$ cabal new-haddock slay-core
Build profile: -w ghc-8.2.2 -O1
In order, the following will be built (use -v for more details):
 - slay-core-0 (lib) --enable-profiling (file src/Slay/Core.hs changed)
Preprocessing library for slay-core-0..
Running Haddock on library instantiated with Slay.Number = <Slay.Number>
for slay-core-0..
Warning: The documentation for the following packages are not installed. No
links will be generated to these packages: reflection-2.1.2
Haddock coverage:
<command line>: unknown package: hole
cabal: Failed to build documentation for slay-core-0.

What does this line mean?

<command line>: unknown package: hole

I'm not using any hole package, looks like some internals leaking.

[int-index]

Alright, I figured out where this hole error comes from. To reproduce, add {-# LANGUAGE TemplateHaskell #-} on top of pkg-example/src/Pkg/Core.hs, or add it to default-extensions.

[int-index]

Summary so far:

• to trigger documentation generation I need to introduce file changes
• for signatures the documentation is not generated
• with TemplateHaskell enabled, Haddock is looking for some hole package

[ezyang]

I feel like I have successfully manually generated documentation for signatures before, c.f. http://next.hackage.haskell.org:8080/package/str-sig-0.1.0.2/docs/Str.html but it is possible that someone introduced a regression to Haddock when I wasn't looking. But I did have to work somewhat hard to make it work, since when I did this documentation generation new-haddock didn't exist, so I basically manually ran Setup haddock command with an appropriately new-build'ed dist dir.

I can definitely believe Haddock with Template Haskell isn't working, this code path was never tested.

[ezyang]

@int-index If possible, could you try a build of GHC with this patch? https://phabricator.haskell.org/D4234 I think I may have accidentally fixed this one too.

[int-index]

If possible, could you try a build of GHC with this patch? https://phabricator.haskell.org/D4234

I tried to test it, but Haddock master does not compile with GHC HEAD (+ your patch) for an unrelated reason:

Configuring library for xhtml-3000.2.2..
Preprocessing library for xhtml-3000.2.2..
Building library for xhtml-3000.2.2..
[ 1 of 15] Compiling Text.XHtml.BlockTable ( Text/XHtml/BlockTable.hs, dist/build/Text/XHtml/BlockTable.o )
[ 2 of 15] Compiling Text.XHtml.Internals ( Text/XHtml/Internals.hs, dist/build/Text/XHtml/Internals.o )

Text/XHtml/Internals.hs:70:10: error:
    Not in scope: type constructor or class ‘Sem.Monoid’
    Module ‘Data.Semigroup’ does not export ‘Monoid’.
   |
70 | instance Sem.Monoid Html where
   |          ^^^^^^^^^^
cabal: Failed to build ghc-paths-0.1.0.9 (which is required by exe:haddock
from haddock-2.18.2). See the build log above for details.
Failed to build xhtml-3000.2.2 (which is required by exe:haddock from
haddock-2.18.2). See the build log above for details.

[alexbiehl]

@int-index please try haddock/ghc-head branch. Master only build with current ghc stable.

[int-index]

@alexbiehl Thank you for the suggestion, but it appears that haddock/ghc-head is out of date, as it fails with the same error.

[int-index]

I made another attempt to reproduce this with ghc-head, this time using the one from hvr-ppa (since D4234 was merged). Two out of three issues are gone:

1. Documentation not generated — reproduced
2. TemplateHaskell causing unknown package: hole — cannot reproduce
3. Missing docs for the Backpack signature — cannot reproduce

Since (1) has its own issue #4506, I am closing this one.