Plutus Docs Setup

Plutus Docs Setup.md

To build a hoogle instance, we currently use a nix-shell with the haskell.nix shellFor function, via the haskell.nix package in the plutus nix expressions, with withHoogle set to true.

See: the haskell.nix docs for how this works.

defer-plugin-errors flag

The tricky part is that the plutus-ledger package will not build under haddock's settings, because of an error reported by the plutus core compilation plugin.

There is a defer-plugin-errors flag provided in the plutus-ledger package, which will silence the plugin errors, allowing haddock to build successfully.

With Nix

Using the haskell.nix setup from the plutus nix expressions we can do something like:

  plutus_ledger_with_docs =
    plutus.plutus.haskell.packages.plutus-ledger.components.library.override {
      doHaddock = true;
      configureFlags = [ "-f defer-plugin-errors" ];
    };

to build the package for docs usage.

In Cabal or Stack

If using cabal or stack to build haddock/hoogle instances the normal way, you can set this flag in cabal.project or stack.yaml or via the commandline invocation of cabal/stack.

You might need some extra setup if you need to use this flag only for building docs.

Other cases where docs fail due to plugin errors

Your docs build can also fail in normal usage if you have plugin errors in your own code.

You can work around this by doing the same setup as the defer-plugin-errors package flag for plutus-ledger:

if flag(defer-plugin-errors)
   ghc-options: -fplugin-opt PlutusTx.Plugin:defer-errors 

(From: plutus-ledger.cabal)