parochial-0.2.0.0: README.md

# 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](hoogle.haskell.org/) 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](https://www.stackage.org/) which doesn't include everything on
  [Hackage](https://hackage.haskell.org).

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 _think_
  [cabal-helpr](https://hackage.haskell.org/package/cabal-helper) 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:

```bash
parochial haddock
```

and hoogle:


```bash
parochial hoogle
```

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

for haddock:

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

and hoogle:

```bash
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:

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

and hoogle:

```bash
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:

```bash
setcap CAP_NET_BIND_SERVICE=ep $(which caddy)
```


### Command line hoogle

You can specify the database on the command line, like so:

```bash
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.