Playing with documents on ASCIIDOC

DISCLAIMER: This is just a small article with some ideas around how to implement an automated process that helps unloading some of the burden of getting documentation formatted on a standarized way. It still requires a lot of work to buid a real "standarized and automated" documentation solution.

In Sorint Spain we've been playing around with alternatives to the "word document" approach for a while. Libre office is free and a great tool, but we found that collaborating, and specially maintaining document formatting between different people on the team, has been so far almost impossible without investing great loads of time.

On this documentation process, we started looking at Markdown first as it was the "language" that we were using to document our git repositories, and even though MD is easy to learn and offers many different formats, we eventually found that ASCIIDOC allowed us to go a little bit further with content formatting, specially as we needed an easy way to produce documentation in a PDF format as a deliverable for our customers. Anyway, the point of this article is not going into a discussion of the tool, but offering a first step to start considering how to implement a "DOCaaS" (documentation as a service) solution (great imagination there for the name XD).

These are the objectives that I'm looking for:

• Easy adoption: ASCIIDOC is quite simple to start using.
• Standard format, but saving time from the person writing or reviewing the document: asciidoctor-pdf is a great tool that allows defining as code the format for our documents See themes here.
• Easy to set up: that's where I was looking at usign a containarized option to generate the docs.
• Automated: I'm treating the format and documentation as code, so creating a pipeline seems as a great way to start here.

Those are the main ideas behind, and below you can find the an example of a first implementation of it (nothing fancy so far). I didn't want to write a long article about it, so if you need more details, help testing this or want to share your experiences around it, please feel free to contact me.

• The Dockerfile to create the container image:

FROM alpine:3.15

RUN apk add ruby --no-cache && \
    gem install rghost hexapdf text-hyphen asciidoctor-pdf && \
    gem install rouge pygments.rb coderay && \
    addgroup -g 1000 nonpriv && adduser -u 1100 -G nonpriv -D localuser && \
    mkdir /shared_vol && chown localuser:nonpriv /shared_vol

USER localuser

VOLUME /shared_vol

WORKDIR /shared_vol

ENTRYPOINT ["/usr/bin/asciidoctor-pdf"]

CMD ["--h"]

• Example of Pipeline for Gitlab (notice I'm not uploading the image to a repository in this example):

generate-pdf-job:
  variables:
    GIT_INPUT_ADOC_FILE: main.adoc
    GIT_ARTIFACT_NAME: test.pdf
  image: docker:latest
  stage: build
  artifacts:
    name: rendered_doc
    paths:
      - ${GIT_ARTIFACT_NAME}
    expire_in: 1 week
  services:
    - docker:dind
  script:
    - docker build .
    - docker run -v ${PWD}:/shared_vol $(docker images | awk '{print $3}' | awk 'NR==2') -b pdf --trace -o ${GIT_ARTIFACT_NAME} ${GIT_INPUT_ADOC_FILE}

A couple of screenshots of how it looks in GitLab: