Help Manage project specific documentation.

Parochial helps manage local documentation by creating an index of a project's html, it also builds a hoogle index. In both instances the project's transitive dependencies are included.

Parochial

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 documentation in $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.

Benefits

• Fast.
• 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 Hackage.

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.

Limitations

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 --state option.
• 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 thinkcabal-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!

Usage

Building the Documentation

parochial --help displays a help message.

If the project contains a single binary the following will work:

for haddock:

parochial haddock

and hoogle:

parochial hoogle

If the project containes a single library then you will need to provide the --state option:

for haddock:

parochial haddock --state $(find . -name setup-config)

and hoogle:

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):

for haddock:

find . -name setup-config | xargs -n1 parochial haddock --state

and hoogle:

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:

localhost:80 {
  file_server browse
}

Either change the port number to above 1024 or set the following capability on the caddy 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.

TODO

• 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.