From 472c91d27eaadeb88730c153c27ed5b4d023d1e9 Mon Sep 17 00:00:00 2001 From: Anastasia Alexadrova Date: Thu, 6 Mar 2025 15:39:38 +0100 Subject: [PATCH 1/3] Validated print-site plugin for PDF --- _resourcepdf/overrides/404.html | 9 ++ _resourcepdf/overrides/main.html | 69 +++++++++ _resourcepdf/overrides/partials/banner.html | 9 ++ .../overrides/partials/copyright.html | 14 ++ _resourcepdf/overrides/partials/header.html | 135 ++++++++++++++++++ docs/templates/pdf_cover_page.tpl | 12 ++ mkdocs-base.yml | 33 +++-- mkdocs-pdf.yml | 103 ++++++++++++- requirements.txt | 3 +- 9 files changed, 367 insertions(+), 20 deletions(-) create mode 100644 _resourcepdf/overrides/404.html create mode 100644 _resourcepdf/overrides/main.html create mode 100644 _resourcepdf/overrides/partials/banner.html create mode 100644 _resourcepdf/overrides/partials/copyright.html create mode 100644 _resourcepdf/overrides/partials/header.html create mode 100644 docs/templates/pdf_cover_page.tpl diff --git a/_resourcepdf/overrides/404.html b/_resourcepdf/overrides/404.html new file mode 100644 index 000000000..3d3717301 --- /dev/null +++ b/_resourcepdf/overrides/404.html @@ -0,0 +1,9 @@ +{#- + This file was automatically generated - do not edit +-#} +{% extends "main.html" %} +{% block content %} +

404 - Not found

+

+We can't find the page you are looking for. Try using the Search or return to homepage .

+{% endblock %} diff --git a/_resourcepdf/overrides/main.html b/_resourcepdf/overrides/main.html new file mode 100644 index 000000000..6f02aa976 --- /dev/null +++ b/_resourcepdf/overrides/main.html @@ -0,0 +1,69 @@ +{# +MkDocs template for builds with Material theme to customize docs layout +by adding marketing-requested elements +#} + +{# Import the theme's layout. #} +{% extends "base.html" %} + + + {% 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 %} + + {% block content%} + + {{ super() }} + + + + {% endblock %} \ No newline at end of file diff --git a/_resourcepdf/overrides/partials/banner.html b/_resourcepdf/overrides/partials/banner.html new file mode 100644 index 000000000..830718b90 --- /dev/null +++ b/_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 +
+
\ No newline at end of file diff --git a/_resourcepdf/overrides/partials/copyright.html b/_resourcepdf/overrides/partials/copyright.html new file mode 100644 index 000000000..dd0f101fa --- /dev/null +++ b/_resourcepdf/overrides/partials/copyright.html @@ -0,0 +1,14 @@ +{#- + This file was automatically generated - do not edit +-#} +
+
+ Percona LLC and/or its affiliates, © {{ build_date_utc.strftime('%Y') }} — Cookie Preferences +
+ {% if not config.extra.generator == false %} + Made with + + Material for MkDocs + + {% endif %} +
\ No newline at end of file diff --git a/_resourcepdf/overrides/partials/header.html b/_resourcepdf/overrides/partials/header.html new file mode 100644 index 000000000..2d0d6e740 --- /dev/null +++ b/_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 %} + + +
+ + +
+
+ + + + + + + + + + Percona Software for PostgreSQL Documentation + +
+
+ + + + + {% if "navigation.tabs.sticky" in features %} + {% if "navigation.tabs" in features %} + {% include "partials/tabs.html" %} + {% endif %} + {% endif %} +
\ No newline at end of file diff --git a/docs/templates/pdf_cover_page.tpl b/docs/templates/pdf_cover_page.tpl new file mode 100644 index 000000000..72a02963b --- /dev/null +++ b/docs/templates/pdf_cover_page.tpl @@ -0,0 +1,12 @@ + +{{ config.extra.added_key }} +

+ +

+

Distribution for PostgreSQL

+{% if config.site_description %} +

{{ config.site_description }}

+{% endif %} +

13.20 (March 6, 2025)

+ + diff --git a/mkdocs-base.yml b/mkdocs-base.yml index 428b4321f..2b864294e 100644 --- a/mkdocs-base.yml +++ b/mkdocs-base.yml @@ -138,31 +138,36 @@ plugins: macros: include_yaml: - 'variables.yml' # Use in markdown as '{{ VAR }}' -# exclude: # Don't process these files -# glob: -# - file.md - with-pdf: # https://github.com/orzih/mkdocs-with-pdf - output_path: '_pdf/PerconaDistributionPostgreSQL-13.pdf' - cover_title: 'Distribution for PostgreSQL Documentation' - cover_subtitle: 13.20 (March 6, 2025) - author: 'Percona Technical Documentation Team' - cover_logo: docs/_images/Percona_Logo_Color.png - debug_html: false - custom_template_path: _resource/templates - enabled_if_env: ENABLE_PDF_EXPORT - mike: version_selector: true css_dir: css javascript_dir: js canonical_version: null + print-site: + add_to_navigation: false + print_page_title: 'Percona Distribution for PostgreSQL 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/templates/pdf_cover_page.tpl" + path_to_pdf: "" + include_css: true + enabled: true extra: version: provider: mike #homepage: # https://docs.percona.com - postgresrecommended: 16 + postgresrecommended: 13 nav: - 'Home': 'index.md' diff --git a/mkdocs-pdf.yml b/mkdocs-pdf.yml index 04fce8a68..5a26e46aa 100644 --- a/mkdocs-pdf.yml +++ b/mkdocs-pdf.yml @@ -1,10 +1,103 @@ # MkDocs configuration for PDF builds -# Usage: ENABLE_PDF_EXPORT=1 mkdocs build -f mkdocs-pdf.yml +# Usage: mkdocs build -f mkdocs-pdf.yml INHERIT: mkdocs-base.yml -copyright: Percona LLC, © 2025 +# Material theme features +theme: + name: material + logo: _images/postgresql-mark.svg + favicon: _images/postgresql-fav.svg + custom_dir: _resourcepdf/overrides/ + font: + text: Roboto + code: Roboto Mono + icon: + edit: material/file-edit-outline + view: material/file-eye-outline + + +nav: + - index.md + - get-help.md + - Get started: + - installing.md + - 1. Install: + - apt.md + - yum.md + - tarball.md + - docker.md + - enable-extensions.md + - repo-overview.md + - 2. Connect to PostgreSQL: + - connect.md + - 3. Manipulate data in PostgreSQL: + - crud.md + - 4. What's next: + - whats-next.md + - Extensions: + - extensions.md + - contrib.md + - percona-ext.md + - third-party.md + - Solutions: + - solutions.md + - High availability: + - solutions/high-availability.md + - solutions/ha-setup-apt.md + - solutions/ha-setup-yum.md + - solutions/pgbackrest.md + - solutions/ha-test.md + - Backup and disaster recovery: + - solutions/backup-recovery.md + - solutions/dr-pgbackrest-setup.md + - Spatial data handling: + - solutions/postgis.md + - solutions/postgis-deploy.md + - solutions/postgis-testing.md + - solutions/postgis-upgrade.md + - ldap.md + - Upgrade: + - major-upgrade.md + - minor-upgrade.md + - migration.md + - troubleshooting.md + - uninstalling.md + - release-notes.md + - release-notes-v13.20.md + - release-notes-v13.18.md + - release-notes-v13.16.md + - release-notes-v13.15.md + - release-notes-v13.14.md + - release-notes-v13.13.upd.md + - release-notes-v13.13.md + - release-notes-v13.12.md + - release-notes-v13.11.md + - release-notes-v13.10.upd.md + - release-notes-v13.10.md + - release-notes-v13.9.md + - release-notes-v13.8.md + - release-notes-v13.7.md + - release-notes-v13.6.upd2.md + - release-notes-v13.6.upd.md + - release-notes-v13.6.md + - release-notes-v13.5.upd2.md + - release-notes-v13.5.upd.md + - release-notes-v13.5.md + - release-notes-v13.4.upd.md + - release-notes-v13.4.md + - release-notes-v13.3.upd3.md + - release-notes-v13.3.upd2.md + - release-notes-v13.3.upd.md + - release-notes-v13.3.md + - release-notes-v13.2.upd4.md + - release-notes-v13.2.upd3.md + - release-notes-v13.2.upd2.md + - release-notes-v13.2.upd.md + - release-notes-v13.2.md + - release-notes-v13.1.md + - release-notes-v13.0.md + - telemetry.md + - licensing.md + - trademark-policy.md -markdown_extensions: - pymdownx.tabbed: {} - admonition: {} \ No newline at end of file diff --git a/requirements.txt b/requirements.txt index 031d9e13a..cbcb20b8d 100644 --- a/requirements.txt +++ b/requirements.txt @@ -15,4 +15,5 @@ mkdocs-htmlproofer-plugin mkdocs-meta-descriptions-plugin mike Pillow > 10.1.0 -mkdocs-open-in-new-tab \ No newline at end of file +mkdocs-open-in-new-tab +mkdocs-print-site-plugin From ab3ec9f344e740286e2facb49fc7ebb62b95b056 Mon Sep 17 00:00:00 2001 From: Anastasia Alexadrova Date: Thu, 6 Mar 2025 17:24:15 +0100 Subject: [PATCH 2/3] Updated Contributing guide --- CONTRIBUTING.md | 25 ++++++++++++++++--------- 1 file changed, 16 insertions(+), 9 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c87fac8be..b36079a02 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -30,12 +30,13 @@ There are several active versions of the documentation. Each version derives fro Each version has a branch in the repository named accordingly: -- 11 -- 12 -- 13 +- 11 (EOL) +- 12 (EOL) +- 13 (EOL) - 14 - 15 - 16 +- 17 The source .md files are in the ``docs`` directory. @@ -146,14 +147,17 @@ The PDF document is in the ``site/pdf`` folder. ``` 6. To build the PDF documentation, do the following: - - Install [mkdocs-with-pdf plugin](https://pypi.org/project/mkdocs-with-pdf/) + - Install [mkdocs-print-site-plugin](https://timvink.github.io/mkdocs-print-site-plugin/index.html) - Run the following command ```sh mkdocs build -f mkdocs-pdf.yml ``` -The PDF document is in the ``site/pdf`` folder. +This creates a single HTML page for the whole doc project. You can find the page at `site/print_page.html`. + +7. Open the `site/print_page.html` in your browser and save as PDF. Depending on the browser, you may need to select the Export to PDF, Print - Save as PDF or just Save and select PDF as the output format. + ## Repository structure @@ -167,13 +171,16 @@ The repository includes the following directories and files: - `_images` - Images, logos and favicons - `css` - Styles - `js` - Javascript files -- `_resource`: - - `templates`: + - `templates`: - ``styles.scss`` - Styling for PDF documents - - `theme`: + - `pdf_cover_page.tpl` - The PDF cover page template +- `_resource`: + - `overrides` - The directory with customized templates for HTML output - `main.html` - The layout template for hosting the documentation on Percona website - - overrides - The folder with the Material theme template customization for builds +- `_resourcepdf`: + - `overrides` - The directory with customized layout templates for PDF - `.github`: - `workflows`: - `main.yml` - The workflow configuration for building documentation with a GitHub action. (The documentation is built with `mike` tool to a dedicated `publish` branch) - `site` - This is where the output HTML files are put after the build +- `snippets` - The folder with pieces of documentation used in multiple places From cdddc05982b311418a68a4a4fa2528f553b17945 Mon Sep 17 00:00:00 2001 From: Anastasia Alexadrova Date: Mon, 31 Mar 2025 12:03:25 +0200 Subject: [PATCH 3/3] Reworked to use 2 configs --- _resourcepdf/overrides/partials/banner.html | 2 +- _resourcepdf/overrides/partials/header.html | 135 -------------------- docs/enable-extensions.md | 3 - mkdocs-pdf.yml | 103 --------------- mkdocs.yml | 7 +- 5 files changed, 4 insertions(+), 246 deletions(-) delete mode 100644 _resourcepdf/overrides/partials/header.html delete mode 100644 mkdocs-pdf.yml diff --git a/_resourcepdf/overrides/partials/banner.html b/_resourcepdf/overrides/partials/banner.html index 830718b90..7e130f43f 100644 --- a/_resourcepdf/overrides/partials/banner.html +++ b/_resourcepdf/overrides/partials/banner.html @@ -4,6 +4,6 @@
- Get help from Percona + Get help from Percona
\ No newline at end of file diff --git a/_resourcepdf/overrides/partials/header.html b/_resourcepdf/overrides/partials/header.html deleted file mode 100644 index 2d0d6e740..000000000 --- a/_resourcepdf/overrides/partials/header.html +++ /dev/null @@ -1,135 +0,0 @@ - - - -{% 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 %} - - -
- - -
-
- - - - - - - - - - Percona Software for PostgreSQL Documentation - -
-
- - - - - {% if "navigation.tabs.sticky" in features %} - {% if "navigation.tabs" in features %} - {% include "partials/tabs.html" %} - {% endif %} - {% endif %} -
\ No newline at end of file diff --git a/docs/enable-extensions.md b/docs/enable-extensions.md index 57992b02f..096e87dae 100644 --- a/docs/enable-extensions.md +++ b/docs/enable-extensions.md @@ -136,8 +136,6 @@ After the installation, enable the following option in `postgresql.conf` configu wal_level = logical ``` -<<<<<<< HEAD -======= Start / restart the server to apply the changes. ## pgvector @@ -148,7 +146,6 @@ To get started, enable the extension for the database where you want to use it: CREATE EXTENSION vector; ``` ->>>>>>> 7845a94c... PG-1214 Documented install and enable pgvector steps ## Next steps [Connect to PostgreSQL :material-arrow-right:](connect.md){.md-button} \ No newline at end of file diff --git a/mkdocs-pdf.yml b/mkdocs-pdf.yml deleted file mode 100644 index 5a26e46aa..000000000 --- a/mkdocs-pdf.yml +++ /dev/null @@ -1,103 +0,0 @@ -# MkDocs configuration for PDF builds -# Usage: mkdocs build -f mkdocs-pdf.yml - -INHERIT: mkdocs-base.yml - -# Material theme features -theme: - name: material - logo: _images/postgresql-mark.svg - favicon: _images/postgresql-fav.svg - custom_dir: _resourcepdf/overrides/ - font: - text: Roboto - code: Roboto Mono - icon: - edit: material/file-edit-outline - view: material/file-eye-outline - - -nav: - - index.md - - get-help.md - - Get started: - - installing.md - - 1. Install: - - apt.md - - yum.md - - tarball.md - - docker.md - - enable-extensions.md - - repo-overview.md - - 2. Connect to PostgreSQL: - - connect.md - - 3. Manipulate data in PostgreSQL: - - crud.md - - 4. What's next: - - whats-next.md - - Extensions: - - extensions.md - - contrib.md - - percona-ext.md - - third-party.md - - Solutions: - - solutions.md - - High availability: - - solutions/high-availability.md - - solutions/ha-setup-apt.md - - solutions/ha-setup-yum.md - - solutions/pgbackrest.md - - solutions/ha-test.md - - Backup and disaster recovery: - - solutions/backup-recovery.md - - solutions/dr-pgbackrest-setup.md - - Spatial data handling: - - solutions/postgis.md - - solutions/postgis-deploy.md - - solutions/postgis-testing.md - - solutions/postgis-upgrade.md - - ldap.md - - Upgrade: - - major-upgrade.md - - minor-upgrade.md - - migration.md - - troubleshooting.md - - uninstalling.md - - release-notes.md - - release-notes-v13.20.md - - release-notes-v13.18.md - - release-notes-v13.16.md - - release-notes-v13.15.md - - release-notes-v13.14.md - - release-notes-v13.13.upd.md - - release-notes-v13.13.md - - release-notes-v13.12.md - - release-notes-v13.11.md - - release-notes-v13.10.upd.md - - release-notes-v13.10.md - - release-notes-v13.9.md - - release-notes-v13.8.md - - release-notes-v13.7.md - - release-notes-v13.6.upd2.md - - release-notes-v13.6.upd.md - - release-notes-v13.6.md - - release-notes-v13.5.upd2.md - - release-notes-v13.5.upd.md - - release-notes-v13.5.md - - release-notes-v13.4.upd.md - - release-notes-v13.4.md - - release-notes-v13.3.upd3.md - - release-notes-v13.3.upd2.md - - release-notes-v13.3.upd.md - - release-notes-v13.3.md - - release-notes-v13.2.upd4.md - - release-notes-v13.2.upd3.md - - release-notes-v13.2.upd2.md - - release-notes-v13.2.upd.md - - release-notes-v13.2.md - - release-notes-v13.1.md - - release-notes-v13.0.md - - telemetry.md - - licensing.md - - trademark-policy.md - diff --git a/mkdocs.yml b/mkdocs.yml index 5bc02a97f..182e28325 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -5,6 +5,9 @@ INHERIT: mkdocs-base.yml site_url: "https://docs.percona.com/postgresql/" +theme: + name: material + custom_dir: _resourcepdf/overrides/ extra: analytics: @@ -26,8 +29,4 @@ extra: feedback form. -#markdown_extensions: -# - pymdownx.tabbed: -# alternate_style: true -