Percona Monitoring and Management (PMM) is a free, open-source, database monitoring solution.
This repo holds the source files for the PMM technical documentation published at https://www.percona.com/doc/percona-monitoring-and-management/.
To contribute to the documentation, you can:
-
report a general problem -- open an Issue in this repo or use Percona's Jira.
-
report a problem on a page -- on every page of our documentation is a link, Report a problem with this page, a shortcut to this repo's Issues. (The link pre-fills the issue's subject so we know what page you're on.) Click, explain, and we'll fix it.
-
fix a problem yourself -- there is also an Edit this page link that will bring you to this repo to edit the Markdown source file for that page. Make your changes (you'll have to fork the repo unless you're Percona staff) and submit a PR which we'll review and adjust where necessary before merging and publishing. If the changes are more than a few lines, you might want to build the website locally to see how it looks in context. To do that, read on.
Links on the PMM Technical Documentation home page
We use MkDocs to convert Markdown files into a static HTML website (or PDF). This process is called building the documentation.
The documentation is in the docs directory. To know about other files in this repo, jump to Directories and files.
We use different branches for PMM versions:
mainis for PMM 2 (latest)1.xis for PMM 1
Before you start, you'll need to know:
- what git, Python 3 and Docker are;
- what Markdown is and how to write it;
- how to install and run those things on the command line.
(If you don't, open an Issue instead.)
- Clone this repository
- Change directory to
pmm-doc - Either:
-
Use our Docker image to build the documentation (create a static web site in the
sitesubdirectory):docker run --rm -v $(pwd):/docs perconalab/pmm-doc-md -
Find the
sitedirectory, openindex.htmlin a browser to view the first page of documentation.
We use a custom theme for our CMS so documentation built this way is unstyled (there's no outer <html> tag, the <head> tag is ignored, and there's some custom stuff for navigation and version switching).
A themed version looks much better and is just as easy. Run this instead:
docker run --rm -v $(pwd):/docs perconalab/pmm-doc-md mkdocs build -t material
If you'd like to see how things look as you edit, MkDocs has a built-in server for live previewing. After (or instead of) building, run:
docker run --rm -v $(pwd):/docs -p 8000:8000 perconalab/pmm-doc-md mkdocs serve -t material --dev-addr=0.0.0.0:8000
and point your browser to http://localhost:8000.
-
Install Python 3
-
Install MkDocs and required extensions:
pip install -r requirements.txt -
Build the site:
mkdocs build -t material -
Open
site/index.html
Or run the built-in web server:
mkdocs serve -t material
And view the site at http://localhost:8000
To generate a PDF version of the documentation:
with Docker:
docker run --rm -v $(pwd):/docs perconalab/pmm-doc-md mkdocs build -f mkdocs-pdf.yml
without:
mkdocs build -f mkdocs-pdf.yml
You'll find the PDF in site_pdf/_pdf.
Note The HTML version includes an SVG site map (created by
resources/Map.puml) that's not in the PDF. This is done by having two index pages (index.mdfor HTML,index-pdf.mdfor PDF) both includingwelcome.md, the core of the home page.
bin(master only):glossary.tsv: Export from a spreadsheet of glossary entriesmake_glossary.pl: Script to write Markdown page fromglossary.tsvgrafana-dashboards-descriptions.py: Script to extract dashboard descriptions from https://github.com/percona/grafana-dashboards/
docs: Base directory for MkDocsresources(master only):*.puml: PlantUML diagrams (see comments inside each)
templates: Stylesheet for PDF output (used by mkdocs-with-pdf extension)theme: MkDocs templates that produce HTML output for percona.com hostingextra.yml: Miscellaneous values and website links (some are also in theextrasection ofmkdocs.yml)icon.yml: A convenience list of icon variables. Use them in Markdown with{{ icon.NAME }}(master only)mkdocs-pdf.yml: Main configuration file for building PDFmkdocs.yml: Main configuration file for building HTMLrelease.yml: The PMM release and version numberrequirements.txt: Python package dependencies
We are trialing the use of mike to build different versions.
With this, MkDocs is run locally and the HTML committed (and optionally pushed) to the publish branch. The whole branch is then copied (by us, naturally) to our web server.
(This is why the PMM1 docs (previously in https://github.com/percona/pmm) have been migrated from Sphinx/rst to Markdown/md and moved to the 1.x branch of this repository.)