Creating PDF from Asciidoc

At Red Hat Systems Engineering we use an internal GitLab to store our repositories, most of the stuff I work on currently is documentation. And we write documentation using Asciidoc (and Asciidoctor to transform it to PDF).

While writing new chapters and merging stuff from other colleagues is straight forward, I would like to get rid of that boring manual generation of PDF.

GitLab provides a wonderful builds feature on a per project base, so lets enable this for a Asciidoc documentation repository and see what it can do for us.

As the builds feature is part of GitLab CI, we need to perform three basic steps to take advantage of it:

  • Create a new project (done, the Asciidoc repo, right?!)

  • Add .gitlab-ci.yml to the git repository and push to GitLab

  • Provision a Runner

Provisioning a Runner

A Runner runs the builds that you define in .gitlab-ci.yml. A Runner can be a virtual machine, a bare-metal machine, a docker container or even a cluster of containers.

I have choosen to provide a runner as a VM on OS1, but you can also use AWS or GCE or … That VM is a RHEL7.2 based host that will run docker containers. It literally took 7 minutes to set it up:

That’s it, done.

Configuring GitLab CI

Now that we have a runner, we can configure our project do perform CI steps after pushes.

To do this, we need to add a .gitlab-ci.yml to the root of the repository. This will tell the runner what to do:

  • per se the runner will git clone (or fetch) the master’s HEAD

  • we need to tell the runner which docker container images to run

  • and we need to define a job that tells the runner what to do

Anyway, it is quiet easy to do that:

  image: asciidoctor/docker-asciidoctor

  stages:
    - build

  asciidoc2pdf:
    stage: build
    script:
      - dnf install -y git
      - mkdir /root/.ssh
      - echo -e "Host gitlab.example.com\n\tStrictHostKeyChecking no\n" >> /root/.ssh/config
      - git submodule update --init
      - asciidoctor-pdf -r asciidoctor-diagram  SOME.asciidoc
    artifacts:
      paths:
        - SOME.pdf

After adding this to the repository, each push will trigger a build, each build will generate a PDF, and each successful build will generate an artifacts archive (which is an zip file downloadable from the build page)

Caveat

The generated PDF (GitLab CI calls this an artifact) is included in a zip file per each (successful) build. So its not very user friendly to get the final result: you need to brows to the most current successful build, download the artifacts, extract the zip file and open the PDF.

Next Steps

I need to work on providing an easy way to get the generated PDF. Ideas?