What does `stack haddock --skip <pkgname>` do?

After being unable to run stack haddock on my project because one package causes it to hang (see How to show progress of `stack haddock`? ) I tried to skip that package with

stack haddock --skip haskell-src-exts

But it still tries to haddock haskell-src-exts anyway (and hangs). What is --skip supposed to do?

--skip was introduced in stack 1.6.1 to avoid building a specific component of a project. A component corresponded to a test suite, an executable or a benchmark suite. As backpack support is implemented, this will have to include libraries, too.

From stack build --help

--skip ARG Skip given component, can be specified multiple times

The docs go into more detail.

• --skip, to skip building components of a local package. It allows you to skip test suites and benchmark without specifying other components (e.g. stack test --skip long-test-suite will run the tests without the long-test-suite test suite). Be aware that skipping executables won't work the first time the package is built due to an issue in cabal. This option can be specified multiple times to skip multiple components.

For example, a package my-package might have a library, an executable my-executable, and two test suites (unit-tests and integration-tests). To build and run tests, you may run stack test. Adding --skip integration-tests will cause the integration-tests component not to be built (nor run).

Unfortunately, the current version of stack (1.9 branch) does not support skipping haddock for individual dependencies, though there is something like this due in the near future. I encountered this exact same problem (with haskell-src-exts). For now, I suggest skipping all haddock dependencies (--no-haddock-deps).

You may wish to invoke haddock with stack exec -- haddock if you wish to pass arguments to haddock which do not work with the stack flag --haddock-arguments.