Using Nix in Docker to build Sphinx documents

About

Sphinx is a documentation generator which is based on a plain text format for its sources. Typically it uses Restructured Text as its source format, thanks to a plugin system, other formats like Markdown can be used as well.

Sphinx allows to render the documentation into various formats. The PDF output is based on LaTeX and at times somewhat tricky to set up. In this post I describe a fairly lightweight setup which I found based on the combination of Nix and Docker.

Chosen approach

For this need, I wanted to have a container which is targeted for the usage on a developer's machine and it should be easy to build it locally and to customize it if needed. Based on this I decided to avoid the need to have a local setup of Nix for building the container image.

Instead of using Nix' builtin support to generate images for Docker containers, I used a minimal based image which does provide Nix inside of the container, so that I could use it like a regular package manager to install the needed dependencies.

Due to the flexibility in Nix' approach when it comes to customization, I did hope to end up with a fairly small container image which should be also quick to build locally.

Original approach

My original attempt was based on using an existing container specification which the Sphinx project uses for its CI setup out of the repository docker-ci.

With a few tweaks I did end up with a container which allowed to build HTML and also PDF results fairly well. It did have two drawbacks though: The image size was in the range of 2.5 GiB and the time to build the image was in the range of half an hour.

This did not seem to be a good approach in the current time, when people seem to give any approach up to max. 5 minutes to produce some results to work with. This drove me to give a Nix based approach a try.

Found results

The results where quite surprising.

The size of the container image dropped to around 400 MiB and the time to build the image got into the range of about 2 minutes.

For my personal taste I would still like to get the image size further reduced, still I find this is something which one can sufficiently work with.

Technical details

Base image

I found that the image lnl7/nix:2018-03-13 serves well as a base. It has been prepared by LnL7, the sources can be inspected in his Github respository nix-docker and also allow to build and customize the base image on your own (if you want).

FROM lnl7/nix:2018-03-13

Dockerfile

The Nix specific part consists of two steps:

Copy the environment definition file into the container.
Install it via nix-env, so that the packages are available in the container.

I found that running the garbage collector at the end does nicely reduce the final image size.

COPY sphinx-env.nix /tmp

RUN nix-env -f /tmp/sphinx-env.nix -i \
  && nix-env -iA nixpkgs.gnumake \
  && nix-collect-garbage -d

The other fragments are specific to Sphinx and the extension sphinx-autobuild:

RUN mkdir /source
WORKDIR /source

EXPOSE 8000/tcp

CMD sphinx-autobuild \
  --host 0.0.0.0 \
  --port 8000 \
  --ignore '.git/*' \
  --ignore '.*' \
  . _build/html

Nix environment definition

I started by creating a Python environment which contains Sphinx and adds m2r for Markdown support and sphinx-autobuild to make the local workflow nicer by having automatic HTML build being served up in the container:

sphinx-env = python.withPackages(ps: [
  ps.sphinx
  ps.m2r

  sphinx-autobuild
]);

To allow for PDFs to be generated, I also added a customized version of Texlive and combined both into a regular environment:

full-sphinx-env = pkgs.buildEnv {
  name = "full-sphinx-env";
  paths = [
    sphinx-env
  ] ++ (pkgs.lib.optional withPdf latex);
};

Compose specification

docker-compose proved to be especially useful when using containers to run commands in isolation. It allows to nicely specify mappings for ports and volumes, so that the usage is very convenient:

version: '3'
services:

  build:
    image: sphinx-build
    build:
      context: _services
      dockerfile: build.df
    volumes:
      - .:/source
    ports:
      - "8000:8000"

Typical usage

Have sphinx-autobuild available serving the HTML version:

docker-compose up build

Building HTML or PDF in the container:

docker-compose run build make pdflatex
docker-compose run build make html