percona-doc-docker

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

• mkdocs: An Ubuntu-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

Create PDF:

docker run --rm -v $(pwd):/docs -e ENABLE_PDF_EXPORT=1 perconalab/pmm-doc-md mkdocs build -t material

(Read more)

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 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 - Builds PDF.
• 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.
• mkdocs-enumerate-headings-plugin For numbered headings.
• mkdocs-section-index - Add links to section nodes.
• mike - Tool for building and managing versions.
• lightgallery - For zooming images.

Additional Fonts:

• Chivo - To match Percona.com website theme.

Sphinx image

Sphinx extensions:

• sphinx-copybutton Adds a copy button to code blocks.
• sphinx-gitstamp Git datestamp.
• 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