Parochial is a tool for managing local haddocks and hoogle databases. I work in cafes and
on the train plus I live in Australia where the internet speed is, err, somewhat
variable. The other significant benefit I found when learning Haskell (and I'm very
much still in that category) is knowing that I was reading the actual documentation of
the installed library. For example if I searched for a function on
Hoogle I wasn't sure if it was the correct function. In fact
I still find this really useful.
The whole point behind Parochial is to group the documentation on a project by project
basis. For the html documentation it simply builds a symlink farm to the installed
$HOME/.cabal/... (you will need to set the
-haddock ghc option or
set it in
$HOME/.cabal/config to ensure the documentation is built) to a directory
named after the current project in
$XDG_DATA_DIR/parochial. For the hoogle database it
does much the same but instead of building a symlink farm it builds a hoogle database,
again named after the project.
- Works without an internet connection.
- Per project documentation.
- Indexes all project libraries (including transitive dependencies). Hoogle only
indexes Stackage which doesn't include everything on
Of course the downside is that if you don't have the library in your cabal file you won't
have any documentation for it.
This is still fairly raw and at an early stage of development but it's certainly usable
and I will be adding to it over time.
- Only works for Simple distributions.
- Only tested with nix-style local builds.
- Only works for projects that build a binary. You can work around this by specifying
the state file with the
- It's tied to a specific hoogle version so if the docs in
$HOME/.cabal/... were built
with a different version parochial will fail with a version mismatch error.
- It's tied to a specific version of cabal. I think
cabal-helpr should fix this but
I need to look into it more.
- If you want to access the hoogle database from a browser you will need to run
hoogle server manually. This is probably fine if you mainly work on one project but would
become annoying fairly quickly. The hoogle hrefs are
file:///</local/path> which most
browsers will refuse to render.
- I'm sure there are others as well!
Building the Documentation
parochial --help displays a help message.
If the project contains a single binary the following will work:
If the project containes a single library then you will need to provide the
parochial haddock --state $(find . -name setup-config)
parochial hoogle --state $(find . -name setup-config)
It there is more than one library you will need to build each one separately (I want to
fix this in the future):
find . -name setup-config | xargs -n1 parochial haddock --state
find . -name setup-config | xargs -n1 parochial hoogle --state
Reading the Documentation
Serving up the html
I use caddy to serve up the target directory but you can choose whatever you like, it
just needs to be able to serve up some files. The following
Caddyfile should do the job:
Either change the port number to above 1024 or set the following capability on the
binary. As root run:
setcap CAP_NET_BIND_SERVICE=ep $(which caddy)
Command line hoogle
You can specify the database on the command line, like so:
hoogle --database=/$XDG_DATA_DIR/parochial/parochial.hoo Functor
or write a simple wrapper script that infers the name of the database from the CWD or
some other clue.
- Work out a better way of locating the
setup-config parent directory. I basically
recurse the dist directory searching for
setup-config which works but is pretty
simplistic. I would have thought
Cabal would have a way of doing this but I can't
find it. If anyone knows how to do this please do let me know.
- Integrate the local hoogle database and the local haddocks.
- If the project has multiple local packages merge the results so the documentation is
in a single place for the entire project.
- Make the index page less ugly.