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_pdf
target. 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.