Recently, I wanted to make sure that the generated API documentation for my web framework Spock is always available (on the web) and up to date, both with the current release and with the current master branch.

Haskell documentation is generated by haddock and consists of several static .html files split up into various directories. Thus, on one hand, we need a host to host static files and we also need an automation to build the docs when something changes. As we are already using Travis for Spock to build the project and run unit tests I decided to enhance the .travis.yml task to also build and upload documentation. This is very easy with stack, we only need to install hscolour and then add --haddock to our stack build commands. This will build the documentation for our project and all dependencies. The next step is to create an AWS S3 bucket and configure Travis to automatically upload the documentation to the bucket. When creating the bucket, make sure to create an IAM user that can only read/write to that bucket and do nothing more. Now we can upload the docs using the Travis S3 deployment strategy. It basically looks like this for Spock:

deploy:
  on:
    branch: master
  provider: s3
  bucket: spockdocs
  skip_cleanup: true
  acl: public_read
  region: eu-central-1
  local_dir: .stack-work/install/x86_64-linux/lts-6.13/7.10.3/doc/
  access_key_id:
    secure: ....
  secret_access_key:
    secure: ....

Now I’ve redacted the access keys here for brevity, but I don’t have to that because I’ve encrypted them using travis encrypt --add deploy.access_key_id and travis encrypt --add deploy.secret_access_key. Therefore, I am still able to add my .travis.yml file to my repository without sharing the credentials with everyone. The last step is to enable web-hosting for the AWS bucket in the AWS console and that’s it! You can either have one AWS bucket per branch, or, alternatively you just need to make sure that you bump the version of your package after releasing a version such that the documentation of your release version is not overwritten by the work in progress one.

Check out Spock’s .travis.yml file and the Spock documentation.