diff --git a/contrib/pg_tde/documentation/Makefile b/contrib/pg_tde/documentation/Makefile new file mode 100644 index 0000000000000..0343748c537a8 --- /dev/null +++ b/contrib/pg_tde/documentation/Makefile @@ -0,0 +1,42 @@ +# Documentation Makefile. + +DOCDIR := documentation + +ifeq ($(shell basename $(CURDIR)),$(DOCDIR)) + DIR := $(CURDIR) +else + 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 (used in CI) + # This command is used to build and deploy a preview to onrender.com + # Preview URL: https://pmm-doc.onrender.com + + mkdocs build -f $(DIR)/mkdocs.yml + +doc-build-pdf: ## Build documentation in PDF format + docker run --rm --platform=linux/amd64 -v $(DIR):/docs -w /build perconalab/pmm-doc-md:latest \ + bash -c " \ + cp -r /docs/* /build/ && \ + git init && \ + git config user.email 'doc-team@percona.com' && \ + git add --all && \ + git commit -am 'Initial commit' > /dev/null && \ + ENABLE_PDF_EXPORT=1 mkdocs build -f mkdocs-pdf.yml && \ + cp /build/site/pdf/*.pdf /docs/ \ + " + +doc-build-image: ## Build perconalab/pmm-doc-md:latest image + # @docker buildx build --platform=linux/amd64 --progress=plain -t perconalab/pmm-doc-md:latest -f documentation/resources/Dockerfile.build . + +doc-build-preview: ## Build documentation and preview at http://localhost:8000 + docker run --rm -v $(DIR):/docs -e ENABLE_PDF_EXPORT=1 perconalab/pmm-doc-md:latest mkdocs serve -a 127.0.0.1:8001 + +doc-search-icons: ## Search for icons that can be used in documentation + @open https://squidfunk.github.io/mkdocs-material/reference/icons-emojis/#search \ No newline at end of file diff --git a/contrib/pg_tde/documentation/_resource/bin/check-images.sh b/contrib/pg_tde/documentation/_resource/bin/check-images.sh new file mode 100644 index 0000000000000..01fb3a3e4bf9f --- /dev/null +++ b/contrib/pg_tde/documentation/_resource/bin/check-images.sh @@ -0,0 +1,31 @@ +#!/bin/bash + +set -o errexit nounset + +declare -r doc_dir=$(git rev-parse --show-toplevel)/documentation +declare -r img_dir="${doc_dir}/docs/images" +declare -r exceptions="^PMM.png" +declare -r action="${ACTION:-}" +declare file="" + +if [ "$action" != "remove" ]; then + echo "Checking for unused images in documentation..." + echo +else + echo "Removing unused images from documentation..." + echo +fi + +for file in $(ls -1 "${img_dir}"); do + if ! grep -r --include "*.md" --include "mkdocs*.yml" -m 1 -q $file "${doc_dir}"; then + if [[ "$file" =~ ${exceptions} ]]; then + continue + fi + if [ "$action" = "remove" ]; then + echo "Removing ${img_dir}/${file} ..." + rm -f "${img_dir}/${file}" + else + echo "${img_dir}/${file}" + fi + fi +done \ No newline at end of file diff --git a/contrib/pg_tde/documentation/_resourcepdf/.icons/percona/logo.svg b/contrib/pg_tde/documentation/_resourcepdf/.icons/percona/logo.svg new file mode 100644 index 0000000000000..6bb15edb5a483 --- /dev/null +++ b/contrib/pg_tde/documentation/_resourcepdf/.icons/percona/logo.svg @@ -0,0 +1,3 @@ + + + \ No newline at end of file diff --git a/contrib/pg_tde/documentation/_resourcepdf/bin/check-images.sh b/contrib/pg_tde/documentation/_resourcepdf/bin/check-images.sh new file mode 100644 index 0000000000000..01fb3a3e4bf9f --- /dev/null +++ b/contrib/pg_tde/documentation/_resourcepdf/bin/check-images.sh @@ -0,0 +1,31 @@ +#!/bin/bash + +set -o errexit nounset + +declare -r doc_dir=$(git rev-parse --show-toplevel)/documentation +declare -r img_dir="${doc_dir}/docs/images" +declare -r exceptions="^PMM.png" +declare -r action="${ACTION:-}" +declare file="" + +if [ "$action" != "remove" ]; then + echo "Checking for unused images in documentation..." + echo +else + echo "Removing unused images from documentation..." + echo +fi + +for file in $(ls -1 "${img_dir}"); do + if ! grep -r --include "*.md" --include "mkdocs*.yml" -m 1 -q $file "${doc_dir}"; then + if [[ "$file" =~ ${exceptions} ]]; then + continue + fi + if [ "$action" = "remove" ]; then + echo "Removing ${img_dir}/${file} ..." + rm -f "${img_dir}/${file}" + else + echo "${img_dir}/${file}" + fi + fi +done \ No newline at end of file diff --git a/contrib/pg_tde/documentation/_resourcepdf/overrides/main.html b/contrib/pg_tde/documentation/_resourcepdf/overrides/main.html new file mode 100644 index 0000000000000..536b11dcdc1a1 --- /dev/null +++ b/contrib/pg_tde/documentation/_resourcepdf/overrides/main.html @@ -0,0 +1,72 @@ +{#- + This file was automatically generated - do not edit +-#} +{% extends "base.html" %} + +{% block announce %} + This is the Release Candidate 2 (RC2) of Percona Transparent Data Encryption (TDE) extension. +

It is not recommended for production environments at this stage.

+

We encourage you to test it and give your feedback. + This will help us improve the product and make it production-ready faster.

+{% endblock %} + +{% block scripts %} + +{{ super() }} +{% endblock %} + +{% block site_nav %} + {% if nav %} + {% if page.meta and page.meta.hide %} + {% set hidden = "hidden" if "navigation" in page.meta.hide %} + {% endif %} + + {% endif %} + {% if "toc.integrate" not in features %} + {% if page.meta and page.meta.hide %} + {% set hidden = "hidden" if "toc" in page.meta.hide %} + {% endif %} + + {% endif %} + + + + {% endblock %} diff --git a/contrib/pg_tde/documentation/_resourcepdf/overrides/partials/banner.html b/contrib/pg_tde/documentation/_resourcepdf/overrides/partials/banner.html new file mode 100644 index 0000000000000..1553c0301cc1f --- /dev/null +++ b/contrib/pg_tde/documentation/_resourcepdf/overrides/partials/banner.html @@ -0,0 +1,9 @@ +
+

+

For help, click the link below to get free database assistance or contact our experts for personalized support.

+ +
+ + Get help from Percona +
+
diff --git a/contrib/pg_tde/documentation/_resourcepdf/overrides/partials/copyright.html b/contrib/pg_tde/documentation/_resourcepdf/overrides/partials/copyright.html new file mode 100644 index 0000000000000..95c8eaf6cf73d --- /dev/null +++ b/contrib/pg_tde/documentation/_resourcepdf/overrides/partials/copyright.html @@ -0,0 +1,14 @@ +{#- + This file was automatically generated - do not edit +-#} + diff --git a/contrib/pg_tde/documentation/_resourcepdf/overrides/partials/header.html b/contrib/pg_tde/documentation/_resourcepdf/overrides/partials/header.html new file mode 100644 index 0000000000000..1983ab1baef50 --- /dev/null +++ b/contrib/pg_tde/documentation/_resourcepdf/overrides/partials/header.html @@ -0,0 +1,135 @@ + + + +{% set class = "md-header" %} +{% if "navigation.tabs.sticky" in features %} + {% set class = class ~ " md-header--shadow md-header--lifted" %} +{% elif "navigation.tabs" not in features %} + {% set class = class ~ " md-header--shadow" %} +{% endif %} + + +
+ + +
+ +
+ + + + + {% if "navigation.tabs.sticky" in features %} + {% if "navigation.tabs" in features %} + {% include "partials/tabs.html" %} + {% endif %} + {% endif %} +
diff --git a/contrib/pg_tde/documentation/_resourcepdf/templates/styles.scss b/contrib/pg_tde/documentation/_resourcepdf/templates/styles.scss new file mode 100644 index 0000000000000..ccbbe96de6e37 --- /dev/null +++ b/contrib/pg_tde/documentation/_resourcepdf/templates/styles.scss @@ -0,0 +1,118 @@ +/* Style for PDF created by MkDocs with mkdocs-with-pdf plugin (https://pypi.org/project/mkdocs-with-pdf/) */ +@media print { + html { + font-size: 100%; + font-family: "Poppins", sans-serif; + } + + body { + font-family: "Poppins", sans-serif; + color: #00162b; + } + + article { + font-family: "Poppins", sans-serif; + text-align: justify; + } + + pre, + code, + var, + samp, + kbd, + tt { + font-family: monospace; + font-size: 110%; + } + + pre code, + pre var, + pre samp, + pre kbd, + pre tt { + font-size: 110%; + } +} + +@page { + size: a4 portrait; + margin: 25mm 20mm 25mm 20mm; + counter-increment: page; + white-space: pre; + color: #00162b; + + @top-right { + content: string(chapter); + } + + @bottom-left { + content: string(subtitle); + } + + @bottom-center { + content: counter(page)' of 'counter(pages); + } + + @bottom-right { + } +} + +@page :first { + @top-right { + content: ''; + } + + @bottom-right { + content: ''; + } + + @bottom-left { + content: ''; + } +} + +article { + page-break-before: always; + min-height: 100%; +} + +article { + + h1, + h2, + h3 { + border-bottom: 0px solid #fff; + } + + h1>.pdf-order, + h2>.pdf-order, + h3>.pdf-order { + padding-left: 6px; + padding-right: 0.8rem; + } +} + +article h1, +h2, +h3 { + border-bottom: 0px solid #fff; + color: #3e4875; +} + +.admonition { + font-size: 100%; +} + +article div.tabbed-content--wrap { + page-break-inside: auto !important; +} +article div.tabbed-content--wrap * { + page-break-before: auto !important; + page-break-inside: auto !important; +} + +.md-typeset .admonition.note, +.md-typeset details.note { + color: #00162b; + border-color: #fff; +} diff --git a/contrib/pg_tde/documentation/docs/assets/templates/pdf_cover_page.tpl b/contrib/pg_tde/documentation/docs/assets/templates/pdf_cover_page.tpl new file mode 100644 index 0000000000000..cf7b1019edb40 --- /dev/null +++ b/contrib/pg_tde/documentation/docs/assets/templates/pdf_cover_page.tpl @@ -0,0 +1,11 @@ + +{{ config.extra.added_key }} +

+ +

+

Percona Transparent Data Encryption 1.0

+

(June 20, 2025)

+ +{% if config.site_description %} +

{{ config.site_description }}

+{% endif %} \ No newline at end of file diff --git a/contrib/pg_tde/documentation/mkdocs-pdf.yml b/contrib/pg_tde/documentation/mkdocs-pdf.yml index 990732fb25072..1d4ded43eadb2 100644 --- a/contrib/pg_tde/documentation/mkdocs-pdf.yml +++ b/contrib/pg_tde/documentation/mkdocs-pdf.yml @@ -13,3 +13,146 @@ extra_css: markdown_extensions: pymdownx.tabbed: {} admonition: {} + +# Theme settings +theme: + name: material + logo: _images/postgresql-mark.svg + favicon: _images/postgresql-fav.svg + custom_dir: _resourcepdf/overrides/ + font: + text: Roboto + palette: + - media: "(prefers-color-scheme)" + toggle: + icon: material/brightness-auto + name: Color theme set to Automatic. Click to change + - media: "(prefers-color-scheme: light)" + scheme: percona-light + primary: custom + accent: custom + toggle: + icon: material/brightness-7 + name: Color theme set to Light Mode. Click to change + - media: "(prefers-color-scheme: dark)" + scheme: percona-dark + primary: custom + accent: custom + toggle: + icon: material/brightness-4 + name: Color theme set to Dark Mode. Click to change + +extra_css: + - https://unicons.iconscout.com/release/v3.0.3/css/line.css + - https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.4.0/css/font-awesome.min.css + - css/percona.css + - css/design.css + - css/osano.css + - css/postgresql.css + - css/landing.css + +extra_javascript: + - js/version-select.js + - js/promptremover.js + - js/consent.js + +plugins: + - search: + separator: '[\s\-,:!=\[\]()"/]+|(?!\b)(?=[A-Z][a-z])|\.(?!\d)|&[lg]t;' + - open-in-new-tab: + - git-revision-date-localized: + enable_creation_date: true + enabled: !ENV [ENABLED_GIT_REVISION_DATE, True] + - meta-descriptions: + export_csv: false + quiet: false + enable_checks: false + min_length: 50 + max_length: 160 + - section-index # Adds links to nodes - comment out when creating PDF +# - htmlproofer # Uncomment to check links - but extends build time significantly + - glightbox + - macros: + include_yaml: + - 'variables.yml' # Use in markdown as '{{ VAR }}' + - with-pdf: # https://github.com/orzih/mkdocs-with-pdf + output_path: '_pdf/PerconaTDE.pdf' + cover_title: 'Percona Transparent Data Encryption' + cover_subtitle: Release Candidate (2025-03-27) + author: 'Percona Technical Documentation Team' + cover_logo: docs/_images/Percona_Logo_Color.png + debug_html: false + two_columns_level: 3 + custom_template_path: _resource/templates + enabled_if_env: ENABLE_PDF_EXPORT + - print-site: + add_to_navigation: false + print_page_title: 'Percona Transparent Data Encryption 1.0 documentation' + add_print_site_banner: false + # Table of contents + add_table_of_contents: true + toc_title: 'Table of Contents' + toc_depth: 2 + # Content-related + add_full_urls: false + enumerate_headings: false + enumerate_headings_depth: 1 + enumerate_figures: true + add_cover_page: true + cover_page_template: "docs/assets/templates/pdf_cover_page.tpl" + path_to_pdf: "" + include_css: true + enabled: true + +nav: + - index.md + - get-help.md + - features.md + - Overview: + - What is Transparent Data Encryption (TDE)?: + - index/index.md + - index/how-tde-helps.md + - index/how-does-tde-work.md + - index/tde-encrypts.md + - index/table-access-method.md + - index/tde-limitations.md + - index/supported-versions.md + - Get Started: + - install.md + - apt.md + - yum.md + - setup.md + - Configure Key Management (KMS): + - global-key-provider-configuration/index.md + - global-key-provider-configuration/kmip-server.md + - global-key-provider-configuration/kmip-fortanix.md + - global-key-provider-configuration/vault.md + - global-key-provider-configuration/kmip-thales.md + - global-key-provider-configuration/keyring.md + - global-key-provider-configuration/set-principal-key.md + - test.md + - wal-encryption.md + - Technical Reference: + - advanced-topics/index.md + - architecture/index.md + - variables.md + - functions.md + - TDE Operations: + - pg_tde CLI Tools: + - command-line-tools/index.md + - command-line-tools/pg-tde-change-key-provider.md + - command-line-tools/pg-waldump.md + - command-line-tools/pg-tde-checksums.md + - how-to/uninstall.md + - how-to/multi-tenant-setup.md + - how-to/decrypt.md + - faq.md + - Release Notes: + - release-notes/release-notes.md + - release-notes/rc2.md + - release-notes/rc.md + - release-notes/beta2.md + - release-notes/beta.md + - release-notes/alpha1.md + - release-notes/mvp.md + - contribute.md \ No newline at end of file diff --git a/contrib/pg_tde/documentation/requirements.txt b/contrib/pg_tde/documentation/requirements.txt index 87a44fb4e5313..a4e087b51a5b6 100644 --- a/contrib/pg_tde/documentation/requirements.txt +++ b/contrib/pg_tde/documentation/requirements.txt @@ -16,3 +16,4 @@ mike mkdocs-glightbox Pillow > 10.1.0 # Pillow is required for mkdocs-glightbox mkdocs-open-in-new-tab # added to fix the open in new tab issue with mkdocs-material +mkdocs-print-site-plugin # added to fix the print site issue with mkdocs-material