PMM-13597 Add doc-build-pdf make target

documentation/Makefile

@@ -1,19 +1,33 @@
-doc-check-images:   ## Check if all images are used in documentation
-	@documentation/resources/bin/check-images.sh
-
-doc-remove-images:  ## Remove unused images from documentation
-	@ACTION=remove documentation/resources/bin/check-images.sh
+# Documentation Makefile.
 
 DOCDIR := documentation
 
 ifeq ($(shell basename $(CURDIR)),$(DOCDIR))
-	CONFIG_FILE := $(CURDIR)/mkdocs.yml
+	DIR := $(CURDIR)
 else
-	CONFIG_FILE := $(CURDIR)/$(DOCDIR)/mkdocs.yml
+	DIR := $(CURDIR)/$(DOCDIR)
 endif
 
+doc-check-images:   ## Check if all images are used in documentation
+	@$(DIR)/resources/bin/check-images.sh
+
+doc-remove-images:  ## Remove unused images from documentation
+	@ACTION=remove $(DIR)/resources/bin/check-images.sh
+
 doc-build:          ## Build documentation
 	# This command is used to build and deploy a preview to onrender.com
 	# Preview URL: https://pmm-doc.onrender.com
 
-	mkdocs build -f $(CONFIG_FILE)
+	mkdocs build -f $(DIR)/mkdocs.yml
+
+doc-build-pdf:			## Build documentation in PDF format
+	# @docker buildx build --platform=linux/amd64 --progress=plain -t perconalab/pmm-doc-md:latest -f documentation/resources/Dockerfile.build .
+	docker run --rm --platform=linux/amd64 -v $(DIR):/docs -w /build -e ENABLE_PDF_EXPORT=1 perconalab/pmm-doc-md:latest \
+		bash -c "cp -r /docs/* /build/ && \
+		ls -la /build && \
+		git init && \
+		git config user.email '[email protected]' && \
+		git add --all && \
+		git commit -am 'Initial commit' && \
+		mkdocs build -f mkdocs-pdf.yml && \
+		cp /build/site/pdf/*.pdf /docs/"

documentation/README.md

@@ -1,8 +1,8 @@
 # Percona Monitoring and Management (PMM) Documentation
 [![render](https://img.shields.io/badge/pmm--doc-render-Green)](https://pmm-doc.onrender.com/)
-[![Build](https://github.com/percona/pmm-doc/actions/workflows/build.yml/badge.svg?branch=main)](https://github.com/percona/pmm-doc/actions/workflows/build.yml)
-[![Helm](https://github.com/percona/pmm-doc/actions/workflows/helm-tests.yml/badge.svg?branch=main)](https://github.com/percona/pmm-doc/actions/workflows/helm-tests.yml)
-[![Podman](https://github.com/percona/pmm-doc/actions/workflows/podman-tests.yml/badge.svg?branch=main)](https://github.com/percona/pmm-doc/actions/workflows/podman-tests.yml)
+[![Build](https://github.com/percona/pmm/actions/workflows/documentation.yml/badge.svg?branch=v3)](https://github.com/percona/pmm/actions/workflows/documentation.yml)
+[![Helm](https://github.com/percona/pmm/actions/workflows/helm-tests.yml/badge.svg?branch=v3)](https://github.com/percona/pmm/actions/workflows/helm-tests.yml)
+[![Podman](https://github.com/percona/pmm/actions/workflows/podman-tests.yml/badge.svg?branch=v3)](https://github.com/percona/pmm/actions/workflows/podman-tests.yml)
 
 [Percona Monitoring and Management] (PMM) is a database monitoring solution that is free and open-source.
 
@@ -22,7 +22,7 @@ The documentation source files are in the `docs` directory. (Other files in this
 
 The three major PMM versions are kept in separate branches:
 
-- `PMM3-branch` is for PMM 3.x (latest)
+- `v3` is for PMM 3.x (latest)
 
 - `main` is for PMM 2.x 
 
@@ -40,7 +40,7 @@ If you'd like to have a local copy of PMM documentation, or are thinking about c
 
 2. Clone this repository.
 
-3. Change directory to `pmm-doc`.
+3. Change directory to `pmm`.
 
 4. Use our [PMM documentation Docker image] to *build the documentation*:
 
@@ -113,9 +113,9 @@ View the site at <http://0.0.0.0:8000>
 
 ## Directories and files
 
-- `mkdocs-percona.yml`: MkDocs configuration file. Creates unthemed HTML for hosting on percona.com.
+- `mkdocs-base.yml`: Default MkDocs configuration file. Creates (Material) themed HTML for hosting anywhere.
 
-- `mkdocs.yml`: Default MkDocs configuration file. Creates (Material) themed HTML for hosting anywhere.
+- `mkdocs.yml`: MkDocs configuration file. Adds a google tag for hosting on render.com.
 
 - `mkdocs-pdf.yml`: MkDocs configuration file. Creates themed [PDF](#pdf).
 
@@ -141,21 +141,15 @@ View the site at <http://0.0.0.0:8000>
 
     - `templates`: Stylesheet for PDF output (used by [mkdocs-with-pdf](https://github.com/orzih/mkdocs-with-pdf) extension).
 
-    - `theme`:
-
-        - `main.html`: MkDocs template for HTML published on percona.com.
-
 - `requirements.txt`: Python package dependencies.
 
 - `variables.yml`: Values used throughout the Markdown, including the current PMM version/release number.
 
-- `.spelling`: Words regarded as correct by `mdspell` (See [Spelling and grammar](#spelling-and-grammar).)
-
-- `.github`:
+- `../.github`:
 
     - `workflows`:
 
-        - `build.yml`: Workflow specification for building the documentation via a GitHub action. (Uses `mike` which puts HTML in `publish` branch.)
+        - `documentation.yml`: Workflow specification for building the documentation via a GitHub action. (Uses `mike` which puts HTML in `publish` branch.)
 
 - `site`: When building locally, directory where HTML is put.
 
@@ -173,15 +167,15 @@ Here's how it's done.
 
 - `PMM_Home_Dashboard.jpg` is created by [pmm-screenshots-pw](https://github.com/PaulJacobs-percona/pmm-screenshots-pw). If snapped by hand, it should be 1280x1280 pixels, to match the overlay image.
 
-- `PMM_Home_Dashboard_Overlay.png` is exported from `docs/images/PMM_Home_Dashboard_Overlay.drawio` using <https://app.diagrams.net/>.
+- `PMM_Home_Dashboard_Overlay.png` is exported from `documentation/docs/images/PMM_Home_Dashboard_Overlay.drawio` using <https://app.diagrams.net/>.
 
     1. Go to <https://app.diagrams.net/>
 
     2. If it's your first time, select *Device* at the *Save diagrams to:* dialog
 
     3. Click *Open existing diagram*
 
-    4. Navigate to `pmm-doc/docs/images` and select `PMM_Home_Dashboard_Overlay.drawio`
+    4. Navigate to `documentation/docs/images` and select `PMM_Home_Dashboard_Overlay.drawio`
 
     5. If the dashboard layout has changed, replace the *Guide* Layer with a new screenshot and adjust the elements on the *Overlay* layer as needed (To show layers, click View --> Layers). Untick the *Guide* Layer so it is not exported.
 
@@ -205,14 +199,14 @@ Here's how it's done.
 
     9. Click *Device*
 
-    10. Navigate to `pmm-doc/docs/images` and click `PMM_Home_Dashboard_Overlay.png`
+    10. Navigate to `documentation/docs/images` and click `PMM_Home_Dashboard_Overlay.png`
 
     11. Click *Save* and overwrite the current file
 
 The overlay image is merged with a copy of the latest home dashboard using [composite], one of the [ImageMagick] tools.
 
 ```sh
-composite docs/images/PMM_Home_Dashboard_Overlay.png docs/images/PMM_Home_Dashboard.jpg docs/images/PMM_Home_Dashboard_Numbered.png
+composite documentation/docs/images/PMM_Home_Dashboard_Overlay.png documentation/docs/images/PMM_Home_Dashboard.jpg documentation/docs/images/PMM_Home_Dashboard_Numbered.png
 ```
 
 ## Spelling and grammar
@@ -254,16 +248,16 @@ The plugin is installed in our [PMM documentation Docker image] and by the GitHu
 To enable it for local builds, uncomment the line with `htmlproofer` in the `plugins` section of `mkdocs.yml` and parse the build output for warnings.
 
 [Percona Monitoring and Management]: https://www.percona.com/software/database-tools/percona-monitoring-and-management
-[PMM technical documentation]: https://www.percona.com/doc/percona-monitoring-and-management/
-[Jira]: https://jira.percona.com/browse/PMM
+[PMM technical documentation]: https://docs.percona.com/percona-monitoring-and-management/
+[Jira]: https://perconadev.atlassian.net/browse/PMM
 [MkDocs]: https://www.mkdocs.org/
 [Markdown]: https://daringfireball.net/projects/markdown/
 [Git]: https://git-scm.com
 [Python]: https://www.python.org/downloads/
 [Docker]: https://docs.docker.com/get-docker/
 [PMM documentation Docker image]: https://hub.docker.com/repository/docker/perconalab/pmm-doc-md
 [mike]: https://github.com/jimporter/mike
-[GitHub actions]: https://github.com/percona/pmm-doc/actions
+[GitHub actions]: https://github.com/percona/pmm/actions
 [ImageMagick]: https://imagemagick.org/script/download.php
 [composite]: https://imagemagick.org/script/composite.php
 [Node.js]: https://nodejs.org/en/download/

documentation/mkdocs-base.yml

@@ -122,9 +122,9 @@ plugins:
       - "setting-up/client/docker.md"
   # https://github.com/orzih/mkdocs-with-pdf
   with-pdf:
-    output_path: "pdf/PerconaMonitoringAndManagement-3.0.0 ALPHA.pdf"
+    output_path: "pdf/PerconaMonitoringAndManagement-3.0.0-beta.pdf"
     cover_title: "Percona Monitoring and Management Documentation"
-    cover_subtitle: 3.0.0 (May 16, 2024)
+    cover_subtitle: 3.0.0 (December 11, 2024)
     author: "Percona Technical Documentation Team"
     cover_logo: docs/images/Percona_Logo_Color.png
     custom_template_path: resources/templates

documentation/resources/Dockerfile.build

@@ -8,10 +8,20 @@ RUN apt-get install -y git wget unzip python3 python3-pip python3-dev fontconfig
 COPY requirements.txt ./requirements.txt
 RUN pip3 install -r requirements.txt
 
-RUN mkdir -p /usr/share/fonts/chivo && cd /usr/share/fonts/chivo && wget -O Chivo.zip https://fonts.google.com/download?family=Chivo && unzip Chivo.zip
-RUN rm /usr/share/fonts/chivo/Chivo.zip && fc-cache -f && apt-get clean
+ADD Chivo.zip /docs/
+RUN unzip /docs/Chivo.zip -d /usr/share/fonts/chivo/ && \
+    ls -la /usr/share/fonts/chivo/ && \
+    rm -rf /usr/share/fonts/chivo/{*.txt,*.ttf} && \
+    mv -f /usr/share/fonts/chivo/static/* /usr/share/fonts/chivo/ && \
+    rm -rf /usr/share/fonts/chivo/static /docs/Chivo.zip && \
+    fc-cache -f -v && apt-get clean
 
 WORKDIR /docs
 
 EXPOSE 8000
 CMD ["mkdocs","build"]
+
+# To build the image: 
+# - download the Chivo font: https://fonts.google.com/download?family=Chivo
+# - put the Chivo.zip file in the project root folder
+# - build: docker buildx build --platform=linux/arm64 --progress=plain -t perconalab/pmm-doc-md:latest -f documentation/resources/Dockerfile.build .