Documentation and #EMBED

[k0001]

The haddock documentation doesn't render properly “out of the box” when having hyperbole as a dependency for a local project. See these #EMBED examples:

[seanhess]

Oh, that's unfortunate. I'm not sure what to do about this, aside from removing most examples from hackage. I created a pre-processor for the docs which embeds examples from compiled files. This prevents the haddock examples from getting out of sync with API changes.

Can you think of any workarounds?

[seanhess]

I suppose for v1.0 we could remove the pre-processor. The whole idea is that API changes will be uncommon, maybe we don't need it any more.

[k0001]

If just CPP works, then maybe that's the easiest thing. I have used that ocassionaly without problems. See this as an example: https://hackage.haskell.org/package/moto-0.0.4/docs/Moto.html (scroll to the very last line in the source code here https://hackage.haskell.org/package/moto-0.0.4/docs/src/Moto.html)

Alternatively, this pre-processor should be made to run automatically from Setup.hs (or perhaps SetupHooks.hs nowadays, see `https://well-typed.com/blog/2025/01/cabal-hooks).

[seanhess]

Gemini suggested a few other ideas:

You need to tell Cabal that your library depends on the docs executable as a build tool, and tell GHC to use it to process your source files.
Update package.yaml (or .cabal)
Add your docs executable to the build-tool-depends of your library and set the GHC flags.

library:
  # ... other fields ...
  build-tool-depends: 
    - your-package-name:docs
  ghc-options:
    - -F
    - -pgmF=docs

Note: Replace your-package-name with the actual name of your package.
Update your docs Haskell Program
GHC's -pgmF expects the preprocessor to accept three specific command-line arguments. Your Main.hs for the docs executable should look like this:

import System.Environment (getArgs)

main :: IO ()
main = do
  args <- getArgs
  case args of
    [original, input, output] -> do
      -- 1. Read the input file (GHC's temp copy of your source)
      content <- readFile input
      -- 2. Your existing hydration logic: 
      --    Search for #EMBED and replace with code from other modules
      let hydratedContent = transform content 
      -- 3. Write to the output file (where GHC expects the result)
      writeFile output hydratedContent
    _ -> error "Usage: docs <original> <input> <output>"

transform :: String -> String
transform = -- your logic here