Documentation should live with the code. Therefore a common problem is to keep your code documentation beside your source code, in a Git-friendly manner, while also being able to transform it later in a user-friendly format. In other words, you want to keep your documentation written in easy-to-read and easy-to-modify text files while also being able to generate PDF files from it (or HTML).
You may want also to be able to include nice diagrams in your documentation, while also being able to version them in a Git-friendly manner.
The only drawback with the following method is that links internal to the documentation are hard to do right.
This document assumes you’re already familiar with Git. If not, it’s time to be, because it’s fabulous.
Markdown is a lightweight markup language. It allows to create well formated text quickly and easily. It can be versionned with Git nicely. And most of all, it’s very easy to read back.
Pandoc is a document converter. It does support Markdown as input, and can generate various user-friendly output formats like PDF or HTML.
Plantuml is a tool able to generate diagrams from simple text descriptions.
Combining all those tools makes some very heavy commands. The simpler way to keep track of those commands is to use them in a Makefile.
Once you have a working Makefile, it’s easy to use Continuous Integration
to generate the PDF file every time someone pushes in the repository.
One advantage with that is that any good forge will allow you to download
the generated PDF at an address that never changes (for instance
Converting Markdown into PDF
Pandoc can do it. However, if you want to customise the style of the PDF (or HTML), it’s actually to first generate LaTeX from the Markdown. Then you can add style personalisations to the LaTeX code (custom header, table of content, etc). Then you can turn the LaTeX into a PDF or HTML.
Show me the code !
Markdown + Plantuml
It’s important to be able to split the documentation into many markdown files for readability. However, your scripts must be able to figure out in which order they must be read. Therefore file names should be prefixed by a number.
The document title is specified in the Makefile (included as meta-data in the PDF later)
It can run with
image: debian:bullseye variables: DEBIAN_FRONTEND: noninteractive doc: script: - apt-get update -qq - apt-get install -y -qq make - apt-get install -y -qq groff - apt-get install -y -qq librsvg2-bin - apt-get install -y -qq pandoc pandoc-citeproc - apt-get install -y -qq plantuml - apt-get install -y -qq python3 - apt-get install -y -qq python3-pip - apt-get install -y -qq texlive-latex-recommended texlive-xetex - apt-get install -y -qq texlive-luatex texlive-latex-extra context - apt-get install -y -qq librsvg2-bin groff - pip3 install pandoc-plantuml-filter==0.1.2 - make doc.pdf artifacts: paths: - doc.pdf expire_in: 7 days
Note: even with
expire_in, Gitlab always keeps the latest build.