"Modules" section links to non-existing haddock documentation when using cabal flags

[soenkehahn]

http://beta.hackage.haskell.org/package/tagsoup contains a link to the haddock documentation for Text.HTML.Download, but the documentation for that module does not exist.

The cabal file for this package contains a flag ('download') which controls whether the module in question is exposed by the package or not. This seems to confuse hackage.

[dcoutts]

Actually it's a general problem that hackage doesn't know about haddock's hide feature, or in this case conditional modules. The solution is to check in the tarball index which modules exist. The old hackage has the same problem.

[mruegenberg]

A similar problem also occurs here: http://hackage.haskell.org/package/hydra-hs

Things to note in that package:

• it depends on a specific C library being present
• the code only consists of a .hsc file, i.e no "normal" Haskell sources are there
  I'm not sure if haddock can work directly on .hsc files. If not, then the reason is obviousy: even if an attempt to run hsc2hs is made, it fails because the aforementioned C library is not present.

Locally, documentation generation works fine.

[cartazio]

heres the walk through duncan just gave me

[14:35:38] <dcoutts_>    Distribution/Server/Pages/Package.hs
[14:35:39] <carter>  both
[14:35:43] <dcoutts_>    that's where the rendering happens
[14:35:46] <carter>  ok
[14:35:52] <dcoutts_>    you'll see it gets passed in a Maybe URL for the docs
[14:36:03] <dcoutts_>    Nothing for when there are no docs
[14:36:31] <dcoutts_>    that will want to be extended with a tarball index
[14:36:44] <carter>  ok
[14:36:45] <dcoutts_>    so you can look up individual modules to see if their docs are present
[14:36:54] <dcoutts_>    e.g. Maybe (URL, TarIndex)
[14:36:56] <carter>  so is the issue that Internal doesn't have docs?
[14:37:00] <dcoutts_>    yes
[14:37:08] <carter>  but is .Internal public?
[14:37:15] <carter>  thats the part i'm confused by
[14:37:17] <dcoutts_>    it uses {-# HADDOCK_OPTIONS hide #-}
[14:37:22] <carter>  why?
[14:37:40] <dcoutts_>    carter: it's a common convention that Internal modules are semi-public
[14:37:45] <carter>  yes
[14:37:50] <carter>  except when you're bos :)
[14:37:50] <dcoutts_>    so the docs pretend they don't exist
[14:38:03] <carter>  because that discourages casual use?
[14:38:08] <dcoutts_>    yes
[14:38:25] <dcoutts_>    but they are exposed nevertheless

[cartazio]

also

[14:38:56] <dcoutts_>    carter: ok, and so TarIndex comes from Data/TarIndex.hs
[14:39:16] <dcoutts_>    you'd do a lookup on each link
[14:39:22] <dcoutts_>    to see if the target exists
[14:39:34] <dcoutts_>    and finally, where we get the tar index from...

[cartazio]

[14:42:20] <dcoutts_>    carter: so in Distribution/Server/Features/Documentation.hs you'll see code for getting the doc index
[14:42:34] <dcoutts_>    e.g. serveDocumentation which calls withDocumentation
[14:42:37] <carter>  ok
[14:42:44] <dcoutts_>    though that's not exported from the feature, but probably could be
[14:43:42] <dcoutts_>    or add a variation of queryHasDocumentation

[14:43:52] <dcoutts_>    then to put it all together, Distribution/Server/Features/Html.hs
[14:44:10] <dcoutts_>    that calls queryHasDocumentation and packagePage
[14:45:05] <dcoutts_>    so you'd change the call to queryHasDocumentation to a similar query that returns the doc index
[14:46:17] <dcoutts_>    carter: e.g. queryDocumentation ::  MonadIO m => PackageId -> m (Maybe (BlobId, TarIndex))
[14:47:55] <dcoutts_>    carter: so add a queryDocumentation, don't export withDocumentation

[gbaz]

looks like we fixed this, even though i can't track down the PR...