percona-doc-docker

Docker images that include dependencies for building Sphinx- and MkDocs-based Percona documentation.

• mkdocs: An Alpine-based image for building MkDocs/Markdown documentation.
• sphinx: Based on the official Sphinx sphinxdoc/sphinx image.
• sphinx-latexpdf: Based on the official Sphinx sphinxdoc/sphinx-latexpdf image.

Usage

MkDocs projects

Perform a build (mkdocs build):

docker run --rm -v $(pwd):/docs perconalab/pmm-doc-md

Run the live preview local server (mkdocs serve):

docker run --rm -p 8000:8000 -v $(pwd):/docs perconalab/pmm-doc-md mkdocs serve -a 0.0.0.0:8000

Open your browser at http://localhost:8000

Sphinx projects

For HTML:

docker run --rm -v $(pwd):/docs perconalab/percona-doc-sphinx make clean html

For PDF:

docker run --rm -v $(pwd):/docs perconalab/percona-doc-sphinx-latexpdf make latexpdf

Both assume a ./Makefile and Sphinx source files in ./source.

Contents

MkDocs image

Alpine packages:

• python3
• python3-dev
• py-pip

For MkDocs, MkDocs plugins and dependencies:

• build-base
• cairo-dev
• gcc
• gdk-pixbuf-dev
• jpeg-dev
• libffi-dev
• musl-dev
• pango-dev
• zlib-dev
• graphviz
• git (for mkdocs-git-revision-date-plugin)
• OpenJDK11 (for PlantUML)
• font-noto & ttf-inconsolata (fonts)

MkDocs packages and plugins:

• mkdocs - MkDocs itself.
• mkdocs-macros-plugin - Various useful macros.
• mkdocs-exclude - For excluding files from MkDocs processing.
• markdown-include - For including .md files in others.
• mkdocs-material - Base theme.
• mkdocs-with-pdf - Depends on WeasyPrint which depends on py3-cairocffi which doesn't have a wheel and for which the Alpine package is currently in the testing repo and is hence installed separately.
• plantuml-markdown - For PlantUML diagrams.
• mkdocs-git-revision-date-plugin - For 'date last changed' page information.
• mkdocs-material-extensions - For icons.
• mkdocs-bootstrap-tables-plugin - Adds a bootstrap class to tables making them render better.
• mike - Tool for building and managing versions.

Additional Fonts:

• Chivo - To match Percona.com website theme.

Sphinx image

Sphinx extensions:

• sphinx-copybutton Adds a copy button to code blocks.
• sphinx-tabs Allows for tabbed content blocks.
• sphinx_markdown_builder Writes Markdown files from rst sources.
• sphinx_markdown_parser Allows for Markdown files in a Sphinx/rst project.
• sphinxcontrib-srclinks Adds various page links (e.g. to Github) to navigation bar.
• sphinx-reload Automatically rebuilds and serves a Sphinx project.
• pymdown-extensions