Eduardo Trujillo

On a previous post, I covered how to setup continuous integration for Haskell projects using a combination of Stack, Travis CI, and Docker. But what about documentation?

Sweet auto-generated docs!
Sweet auto-generated docs!

If you already have CI setup for your project with Stack and Travis CI, it is actually pretty easy. In fact, you can make use of GitHub’s Pages feature, which hosts statics sites based on the content of the gh-pages branch to host your documentation for free.

The following is a bash script I’ve been using on a couple of projects on GitHub. It takes care of collecting the documentation and coverage reports generated while building the application, triggered using Stack’s --haddock and --coverage respectively.

#!/bin/bash

# .travis/assemble-docs.sh
#
# Make sure you install the Travis CLI and encrypt a GitHub API token with
# access to the repository: `travis encrypt GH_TOKEN=xxxxxxx --add`.
#
# This script is meant to be run during the `after_success` build step.

# Copy haddocks to a separate directory.
mkdir -p ../gh-pages
cp -R "$(stack path --local-doc-root)" ../gh-pages
cp -R "$(stack path --local-hpc-root)" ../gh-pages
cd ../gh-pages

# Set identity.
git config --global user.email "travis@travis-ci.org"
git config --global user.name "Travis"

# Add branch.
git init
git remote add origin https://${GH_TOKEN}@github.com/${TRAVIS_REPO_SLUG}.git > /dev/null
git checkout -B gh-pages

# Push generated files.
git add .
git commit -m "Haddocks updated" git push origin gh-pages -fq > /dev/null

To do its job, the script relies on some neat tricks/hacks to keep the process as simple as possible:

  • Stack: When using --haddock and --coverage flags, Stack will place documentation and coverage reports on specific paths. You can query these paths using stack path. On the script above, we use special flags so the output of the program is a single line with the requested path. This avoids having to think about or trying to find where the compiler placed the documentation and related files.

  • GitHub API Tokens: Managing SSH keys inside a build job is probably something doable but probably not easy. Thankfully, GitHub allows you to push commits to a repository using just an API token.

  • Travis CI encrypted variables: This allows us to conveniently store the aforementioned token in a secure manner and easily access it as an environment variable while the job runs. We do have to use > /dev/null on a couple of places so the key is not leaked on build logs.

  • Bare Git branch: Given that keeping track of history is not a priority and could break the build process if somebody else pushed to the documentation branch, we simply keep a single commit on the gh-pages branch. One can easily do this by initializing a new repository, committing, and force-pushing into the branch.

If you would like to see a public working example, checkout this repository and its build logs on Travis CI. The resulting documentation is available as a GitHub pages website and coverage reports can be found under /hpc on the site.


Eduardo Trujillo

This week I’m flying to Colorado along with some co-workers for this year’s LambdaConf, which is one of the largest conferences focused on Functional Programming out there.

Unlike some conferences I’ve been to in the past, LambdaConf has multiple tracks covering multiple levels of experience. Each track has its own set of talks, which means that you won’t be able to attend all talks, but, and perhaps more importantly, you can sort of mix and match to create your own conference schedule!

So that’s exactly what I did. Below you can see which talks I’m hoping to attend during the conference. It’s a fairly balanced mix of all three tracks (beginner, intermediate, advanced) and a couple of alternatives.

I’m specially interested on the Urbit talk. I’ve read about the project in the past and it almost sounded like something out of (Computer) Science Fiction.

Hands-on and Haskell-related talks also sound like a lot of fun. I’m definitely looking forward to writing my own Lisp interpreter, and learning more about the inner workings of Haskell and advance features in its type system.

NOTE: (1) Some talk names are shortened. (2) OR is used to signify parts of the schedule I’m unsure of.

Thursday

  1. Breakfast
  2. Keynote
  3. Agda from Nothing OR Introduction to Non-Violent Communication
  4. Lunch
  5. Make Your Own Lisp Interpreter (Part 1)
  6. Afternoon Refresh
  7. Make Your Own Lisp Interpreter (Part 2)
  8. Closing Remarks

Friday

  1. Breakfast
  2. Keynote
  3. Type Kwon Do
  4. Lunch
  5. Functional Algebra
  6. Urbit
  7. Afternoon Refresh
  8. On The Shoulders of Giants
  9. Interactive Tests and Documentation via QuickCheck-style Declarations
  10. Recursion Schemes
  11. Closing Remarks
  12. Mystery Dinner

Saturday

  1. Breakfast
  2. Keynote
  3. Functional Web Programming OR Computing vs Computers
  4. Panel: The Functional Front-End OR Computing vs Computers
  5. Who Let Algebra Get Funk with My Data Types?
  6. RankNTypes Ain’t Rank at All
  7. Lunch
  8. The Next Great Functional Programming Language
  9. Manuals are for Suckers
  10. MTL Versus Free
  11. Afternoon Refresh
  12. What Would Happen if REST Were Immutable?
  13. OOP Versus FP
  14. Functional Refactoring
  15. Closing Remarks

Sunday

This is the unconference day. I’ll probably attend one or two of the earliest events, but I will have to take off later in the day given that I have a plane to catch.


Eduardo Trujillo

After using Gentoo for a while, I’ve noticed that while the main portage tree has many up-to-date ebuilds, there are still some that lag behind upstream.

The good news is that, if you’re a bit adventurous, you can add overlays, which, like the name implies, are ebuild trees that are overlaid on top of your local tree.

Overlays usually contain software or package versions that are not available on the main tree. However, it also means that they might not have gone through the same amount of quality assurance than packages from the main tree.

Overlays may be personal or maintained by a small group of developers. They can also exist just locally on your machine or they can be hosted on a git repository.

There’s also tools like layman which can help you manage overlays used on a machine.

So far, my favorite overlays are gnome, steam-overlay, and haskell, which provide a recent version of GNOME (3.20), Steam, and up-to-date Haskell packages respectively.

However, not everything has an ebuild, even if you look on overlays, so you might have to write your own ebuilds.

I’ve been collecting a couple of these and putting them on my own personal overlay hosted on git. This has allowed me to version them and share them across Gentoo machines.

If you are feeling adventurous, you can try it by adding the following file to /etc/portage/repos.conf/chromabits.conf:

[chromabits]
location = /usr/local/overlay/chromabits
sync-type = git
sync-uri = https://phabricator.chromabits.com/diffusion/PORT/portage.git
auto-sync = yes

However, I cannot guarantee that they will build, install correctly, or not start a fire given that I lack the time resources to perform something more advanced than “It works on my machine(s)” in terms of QA.

Here a quick summary of a few goodies included:

  • iio-sensor-proxy: Allows GNOME to automatically adjust the screen brightness.
  • nm-applet: A recent version (1.2) of the NetworkManager applet.
  • corebird: A recent version (1.2) of a great GTK+ Twitter client.
  • slack: The official Slack client for Linux.
  • networkmanager: The latest version of NetworkManager, which has nice features like Wi-Fi power save and MAC address randomization.
  • softether-vpn: The SoftEther VPN server and client.
  • syncthing-gtk: A GTK GUI for Syncthing.

…or you can find more in the archives.