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?!)
.gitlab-ci.ymlto 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:
provision a new RHEL7.2 VM on OS1
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)
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.
I need to work on providing an easy way to get the generated PDF. Ideas?