From 1b07da3d7438a132b26bdeb14a30476a72926cd0 Mon Sep 17 00:00:00 2001 From: Oleg Nenashev Date: Wed, 12 Jun 2024 13:17:30 +0200 Subject: [PATCH 1/4] Add initial PDF generation --- .devcontainer/Dockerfile | 3 +-- .devcontainer/requirements.txt | 6 ++++- mkdocs.yml | 41 +++++++++++++++++++++++++++++++++- 3 files changed, 46 insertions(+), 4 deletions(-) diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile index aca8844..bf4d06d 100644 --- a/.devcontainer/Dockerfile +++ b/.devcontainer/Dockerfile @@ -1,5 +1,4 @@ FROM python:3.10.4-slim-buster RUN apt-get update -RUN apt-get install -y libsass-dev build-essential libcairo2 git - +RUN apt-get install -y libsass-dev build-essential libcairo2 git libpango-1.0-0 libpangoft2-1.0-0 pangocairo-1.0 diff --git a/.devcontainer/requirements.txt b/.devcontainer/requirements.txt index b66c962..7d0a3c3 100644 --- a/.devcontainer/requirements.txt +++ b/.devcontainer/requirements.txt @@ -9,8 +9,9 @@ mkdocs-material[imaging]==9.5.17 mkdocs-multirepo-plugin==0.6.3 mkdocs-redirects==1.2.1 mkdocs-extra-sass-plugin==0.1.0 -mkdocs-render-swagger-plugin===0.1.1 +mkdocs-render-swagger-plugin==0.1.1 mkdocs-pdf==0.1.1 +mkdocs-with-pdf==0.9.3 livereload==2.6.3 lxml==4.9.3 click==8.1.7 @@ -23,10 +24,13 @@ pathspec==0.11.2 platformdirs==3.11.0 python-dateutil==2.8.2 python-slugify==8.0.1 +pypng==0.20220715.0 pyyaml==6.0.1 pyyaml-env-tag==0.1 +qrcode==7.4.2 six==1.16.0 text-unidecode==1.3 typing-extensions==4.8.0 typing-inspect==0.8.0 watchdog==3.0.0 +weasyprint==52.5 diff --git a/mkdocs.yml b/mkdocs.yml index 469fd4c..10f3a54 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,9 +1,10 @@ site_name: Gradle Community Site +site_author: Gradle Contributors site_description: >- This is an open-source site for all Gradle community matters, including governance, artwork, events, and public infrastructure. copyright: > - For content - Copyright © 2024 - All contributors to the repository and included components. + For content - Copyright © 2024 - All contributors to the repository and included components. The original content licenses and copyrights from the included repositories are preserved, you can find them in the linked repositories. @@ -178,6 +179,44 @@ plugins: import_url: 'https://github.com/gradle/actions?branch=main&edit_uri=/blob/main/' imports: [ "README.md", "*" ] + - group: + enabled: !ENV [PDF_BOOK, true] + plugins: + - with-pdf: + author: Gradle Contributors + cover: true + cover_title: The Gradle Cookbook + cover_subtitle: Open Source Recipes for Gradle Build Tool + cover_logo: https://gradle.com/wp-content/themes/fuel/assets/img/branding/gradle-elephant-icon-gradient.svg + back_cover: true + toc_title: Table of Contents + heading_shift: false + toc_level: 3 + ordered_chapter_level: 2 + show_anchors: true + exclude_pages: + - 'README' + - 'CONTRIBUTING' + - 'events/' + - 'contributing/' + - 'projects/' + # custom_template_path: TEMPLATES PATH + #convert_iframe: + # - src: IFRAME SRC + # img: POSTER IMAGE URL + # text: ALTERNATE TEXT + # - src: ... + #two_columns_level: 3 + # + #render_js: true + #headless_chrome_path: headless-chromium + # + #output_path: any-place/document.pdf + #enabled_if_env: ENABLE_PDF_EXPORT + # + #debug_html: true + #verbose: true + - redirects: redirect_maps: From 1d48ca038efb821cb67c338718581a8d74d71b8d Mon Sep 17 00:00:00 2001 From: Oleg Nenashev Date: Wed, 12 Jun 2024 13:39:20 +0200 Subject: [PATCH 2/4] Amend the Pipeline and document building the PDF --- .gitignore | 2 ++ docs/CONTRIBUTING.md | 4 ++++ mkdocs.yml | 56 ++++++++++++++------------------------------ 3 files changed, 24 insertions(+), 38 deletions(-) diff --git a/.gitignore b/.gitignore index b63527f..e6a8f61 100644 --- a/.gitignore +++ b/.gitignore @@ -6,3 +6,5 @@ temp_dir /.idea/misc.xml /.idea/modules.xml /.idea/vcs.xml + +.DS_Store diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 32bf50b..5111961 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -87,6 +87,10 @@ you can run the `build` and the `serve` commands with the `FULL_BUILD=false` var FULL_BUILD=false mkdocs serve ``` +### Building the Cookbook PDF + +Run ` BUILD_PDF=1 mkdocs build` to generate the PDF file in [_site/pdf/document.pdf](./../_site/pdf/document.pdf). + ## CI/CD This site is built and deployed by GitHub Actions. diff --git a/mkdocs.yml b/mkdocs.yml index d279849..5c692a0 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -85,7 +85,7 @@ extra: social: - icon: fontawesome/brands/slack link: https://gradle.org/slack-invite - name: Slack + name: Slack - icon: fontawesome/brands/github link: https://github.com/gradle name: GitHub @@ -181,43 +181,23 @@ plugins: import_url: 'https://github.com/gradle/actions?branch=main&edit_uri=/blob/main/' imports: [ "README.md", "*" ] - - group: - enabled: !ENV [PDF_BOOK, true] - plugins: - - with-pdf: - author: Gradle Contributors - cover: true - cover_title: The Gradle Cookbook - cover_subtitle: Open Source Recipes for Gradle Build Tool - cover_logo: https://gradle.com/wp-content/themes/fuel/assets/img/branding/gradle-elephant-icon-gradient.svg - back_cover: true - toc_title: Table of Contents - heading_shift: false - toc_level: 3 - ordered_chapter_level: 2 - show_anchors: true - exclude_pages: - - 'README' - - 'CONTRIBUTING' - - 'events/' - - 'contributing/' - - 'projects/' - # custom_template_path: TEMPLATES PATH - #convert_iframe: - # - src: IFRAME SRC - # img: POSTER IMAGE URL - # text: ALTERNATE TEXT - # - src: ... - #two_columns_level: 3 - # - #render_js: true - #headless_chrome_path: headless-chromium - # - #output_path: any-place/document.pdf - #enabled_if_env: ENABLE_PDF_EXPORT - # - #debug_html: true - #verbose: true + - with-pdf: + enabled_if_env: BUILD_PDF + author: Gradle Contributors + cover: true + cover_title: The Gradle Cookbook + cover_subtitle: Open Source Recipes for Gradle Build Tool + cover_logo: https://gradle.com/wp-content/themes/fuel/assets/img/branding/gradle-elephant-icon-gradient.svg + back_cover: true + toc_title: Table of Contents + toc_level: 3 + show_anchors: true + exclude_pages: + - ^$ + - 'CONTRIBUTING' + - 'events/' + - 'contributing/' + - 'projects/' - redirects: redirect_maps: From b0efa28b84c851d7f7937461526f1b3083956501 Mon Sep 17 00:00:00 2001 From: Oleg Nenashev Date: Wed, 12 Jun 2024 13:51:14 +0200 Subject: [PATCH 3/4] Add pipeline for generating PDF upon release --- .github/workflows/release.yml | 38 +++++++++++++++++++++++++++++++++++ docs/CONTRIBUTING.md | 2 +- mkdocs.yml | 1 + 3 files changed, 40 insertions(+), 1 deletion(-) create mode 100644 .github/workflows/release.yml diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000..39e4d49 --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,38 @@ +name: Publish the Release +on: + release: + types: [published] + +permissions: + contents: write + +jobs: + cookbook-pdf: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v3 + with: + submodules: "true" + + - name: Set up Python + uses: actions/setup-python@v4 + with: + python-version: "3.10" + + - name: Install dependencies + run: pip install -r .devcontainer/requirements.txt + + - name: Build the docs and the PDF + run: BUILD_PDF=1 mkdocs build + + - name: Upload Release Asset + id: upload-release-asset + uses: actions/upload-release-asset@v1 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + with: + upload_url: ${{ github.event.release.upload_url }} + asset_path: _site/pdf/cookbook.pdf + asset_name: cookbook.pdf + asset_content_type: application/pdf diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 5111961..a62eade 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -89,7 +89,7 @@ FULL_BUILD=false mkdocs serve ### Building the Cookbook PDF -Run ` BUILD_PDF=1 mkdocs build` to generate the PDF file in [_site/pdf/document.pdf](./../_site/pdf/document.pdf). +Run `BUILD_PDF=1 mkdocs build` to generate the PDF file in [_site/pdf/cookbook.pdf](./../_site/pdf/cookbook.pdf). ## CI/CD diff --git a/mkdocs.yml b/mkdocs.yml index 5c692a0..bab7391 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -183,6 +183,7 @@ plugins: - with-pdf: enabled_if_env: BUILD_PDF + output_path: pdf/cookbook.pdf author: Gradle Contributors cover: true cover_title: The Gradle Cookbook From 3bdbad1b94dc5b21d672dfedfc20213c8b953a31 Mon Sep 17 00:00:00 2001 From: Oleg Nenashev Date: Wed, 12 Jun 2024 14:11:23 +0200 Subject: [PATCH 4/4] Override copyright in the book, update the trademark notice --- docs/cookbook/README.md | 11 ++++++++++- mkdocs.yml | 11 +++++++---- 2 files changed, 17 insertions(+), 5 deletions(-) diff --git a/docs/cookbook/README.md b/docs/cookbook/README.md index 160a398..2cfaf20 100644 --- a/docs/cookbook/README.md +++ b/docs/cookbook/README.md @@ -14,7 +14,7 @@ CI/CD tools, IDEs, support for languages and frameworks, and various peripheral tools. -In this document, _Gradle Build Tool_ is abbreviated _Gradle_. +In the Gradle Cookbook, _Gradle Build Tool_ is abbreviated _Gradle_. !!! note The Gradle Cookbook is under active development (see the roadmap item [here](https://github.com/gradle/community/issues/42)). @@ -55,6 +55,15 @@ You can extend the Cookbook by adding new recipes, updating the existing ones, or even creating whole new sections. Check out the [Contributor Guide](./CONTRIBUTING.md) for more information. +## Trademark Notice + +Gradle and the Gradlephant logo (the "Gradle Marks") are registered trademarks of Gradle, Inc. and/or its subsidiaries. +Use of the Gradle Marks the Gradle Cookbook pages is for identification purposes only and does not imply sponsorship or endorsement by Gradle, Inc. +In the Gradle Cookbook, "Gradle" typically means "Gradle Build Tool" and does not reference Gradle Inc. and/or its subsidiaries. + +See the [Gradle Branding Guidelines](https://gradle.com/brand/) for more information about +trademark usage and the approval process. + ## References - [Gradle User Manual](https://docs.gradle.org/current/userguide/userguide.html) diff --git a/mkdocs.yml b/mkdocs.yml index bab7391..51dd361 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -4,13 +4,13 @@ site_description: >- This is an open-source site for all Gradle community matters, including governance, artwork, events, and public infrastructure. copyright: > - For content - Copyright © 2024 - All contributors to the repository and included components. + Copyright © 2024 - All contributors to the repository and included components. The original content licenses and copyrights from the included repositories are preserved, you can find them in the linked repositories. - The GRADLE trademark is the property of Gradle, Inc. - Use of the term GRADLE on this website and any content and/or materials available through this website is - for identification purposes only and does not imply sponsorship or endorsement by Gradle, Inc. + Gradle and the Gradlephant logo (the "Gradle Marks") are registered trademarks of Gradle, Inc. and/or its subsidiaries. + Use of the Gradle Marks the Gradle Cookbook pages is for identification purposes only and does not imply sponsorship or endorsement by Gradle, Inc. + In the Gradle Cookbook, "Gradle" typically means "Gradle Build Tool" and does not reference Gradle Inc. and/or its subsidiaries. docs_dir: docs repo_url: https://github.com/gradle/community repo_name: Gradle Community repo @@ -185,6 +185,9 @@ plugins: enabled_if_env: BUILD_PDF output_path: pdf/cookbook.pdf author: Gradle Contributors + # FIXME: Needs rendering style to include the trademark notice & Co into the header + copyright: > + Copyright © 2024 - All contributors to the repository and included components. cover: true cover_title: The Gradle Cookbook cover_subtitle: Open Source Recipes for Gradle Build Tool