search

haskell / cabal

Official upstream development repository for Cabal and cabal-install
https://haskell.org/cabal
Other
1.62k stars 691 forks source link

`cabal haddock <arbitrary package>` produces nothing #9327

Open mrkkrp opened 1 year ago

mrkkrp commented 1 year ago

Describe the bug / To Reproduce

E.g.

$ cabal haddock text

Produces nothing and exits with 0. Might be because text is only a dependency? But I think it is not unreasonable to expect this to work. The --help says:

Examples:
  cabal haddock pkgname    Build documentation for the package named pkgname

Expected behavior Some documentation should be produced.

System information

$ cabal --version
cabal-install version 3.10.1.0
compiled using version 3.10.1.0 of the Cabal library
$ ghc --version
The Glorious Glasgow Haskell Compilation System, version 9.4.6
ffaf1 commented 1 year ago

This is on top of cabal haddock --help

Usage: cabal haddock [FLAGS] TARGET

Build Haddock documentation for the specified packages within the project.

Any package in the project can be specified. If no package is specified, the
default is to build the documentation for the package in the current
directory. The default behaviour is to build documentation for the exposed
modules of the library component (if any). This can be changed with the
'--internal', '--executables', '--tests', '--benchmarks' or '--all' flags.

Currently, documentation for dependencies is NOT built. This behavior may
change in future.

The important words being within the project.

If you have ideas on how to make the “Example:” section more clear, I am all ears!

ulysses4ever commented 1 year ago

Related discussion:

Would be nice to clean up the help text and articulate a great deal firmer that we work against local packages rather than arbitrary ones.

Ideally, cabal haddock should return non-0 exit code in such cases.

I separate feature request may be filed to extend cabal haddock to work against arbitrary packages. This, obviously, would require much more effort than fixing the docs.

mrkkrp commented 1 year ago

IMHO, it should work for arbitrary packages. I was developing something and the docs of a dependency were not on Hackage. With this feature I could simply do cabal haddock my-package whereas without it I need to locate and clone the repo of each package I'm interested in.

gbaz commented 1 year ago

I think we should keep the scope of this issue narrow so it has a chance of being resolved within the next release. A feature request to extend the haddock command as you suggest would be welcome to be filed as a separate "enhancement" ticket.