Generating MariaDB MaxScale PDF and HTML Documentation

I was recently talking on the #mariadb channel on FreeNode and I got a question about the often overlooked PDF documentation generation. In this blog I will show how to create a set of PDF files of the MariaDB MaxScale’s documentation – a good way to keep the documentation handy. I did this on Ubuntu 14.04, but it should also work on other platforms.

Installing Packages

Since we’ll be configuring MariaDB MaxScale, we’ll need to install a few dependencies for MariaDB MaxScale and also grab the MariaDB server tarball. We start by installing the following packages.

sudo apt-get install git build-essential libssl-dev libaio-dev ncurses-dev bison flex cmake perl libtool libcurl4-openssl-dev libpcre3-dev tcl tcl-dev

Then we’ll get the MariaDB server tarball which contains all the required parts for MariaDB MaxScale and extract it into our home directory.

wget --content-disposition https://downloads.mariadb.org/f/mariadb-10.0.24/bintar-linux-glibc_214-x86_64/mariadb-10.0.24-linux-glibc_214-x86_64.tar.gz/from/http%3A//mirror.netinch.com/pub/mariadb/?serve
tar -axf  mariadb-10.0.24-linux-glibc_214-x86_64.tar.gz

MariaDB MaxScale uses Pandoc and Latex to generate the PDF documentation from the raw Markdown files. This means that we’ll have to install the following extra packages.

sudo apt-get install pandoc texlive texlive-xetex texlive-latex-extra

After installing these packages, we need to clone the MariaDB MaxScale repo, check out the 1.4.1 tag and create a directory where we can generate the PDF documentation.

git clone https://github.com/mariadb-corporation/MaxScale.git
git -C MaxScale checkout 1.4.1
mkdir build
cd build

Creating PDF Documentation

The final step is to configure MaxScale and run the generate_pdftarget. Since we used the binary tarball, we’ll need to define the paths to various files in the extracted tarball in our home directory.

cmake ../MaxScale -DERRMSG=$HOME/mariadb-10.0.24-linux-x86_64/share/english/ 
-DMYSQL_EMBEDDED_LIBRARIES=$HOME/mariadb-10.0.24-linux-x86_64/lib/libmysqld.a 
-DMYSQL_EMBEDDED_INCLUDE_DIR=$HOME/mariadb-10.0.24-linux-x86_64/include/

After configuration, the only thing we need to do is to generate the actual PDF documentation.

make generate_pdf

After the generation is complete, all the PDF files can be found in the pdf/ directory.

Alternative HTML Documentation

MariaDB MaxScale can also create HTML documentation from the Markdown files. Creating it is as simple as running the make generate_html target.

make generate_html

This will create HTML documentation in the html/ directory.

And there we go, two different types of documentation ready for use. Although the contents of the PDF and HTML documents aren’t as smooth as MariaDB MaxScale’s Knowledge Base Articles, they can be a good substitute when browsing on a mobile device or when Internet access isn’t available.