Haskell Package ReadTheDocs Template

This repo contains a template for writing Haskell package introductions and tutorials using ReadTheDocs.

Dowloading and using the template

Install Sphinx:

pip install sphinx sphinx-autobuild

Clone the repository somewhere outside of your repo:

git clone --recurse-submodules https://github.com/m-renaud/haskell-rtd-template.git

Copy the docs directory into your repo:

cp -r haskell-rtd-template/docs /path/to/your/package/

Add submodules:

echo haskell-rtd-template/.gitmodules >> /path/to/your/package/.gitmodules

Build the skeleton:

cd /path/to/your/package/docs/
make html

And you're done! View in your browser by visiting file:///path/to/your/package/docs/_build/html/index.html.

For a full example see the containers documentation.

Uploading to ReadTheDocs

Create an account at ReadTheDocs.
Import your docs and name the project haskell-<package-name> (for example, the containers package would be haskell-containers).
View your new docs at haskell-<package-name>.readthedocs.io!

Note: We prefix the package name with haskell- for consistency across packages since the bare package name won't be available in many cases. If the package name has the haskell- prefix already then just use the package name.

Haskell Specific ReadTheDoc Extension

I've also written a Haddock Autolink extension which allows you to easily link to Haddocks using simple syntax like:

:haddock:`containers`

=> containers

:haddock:`containers/Data.Sequence`

=> Data.Sequence

:haddock:`containers/Data.Sequence#empty`

=> Data.Sequence#empty

See the README for more info.