From e46595cdacc57d8a76e8945c7aab5e28686b7f9d Mon Sep 17 00:00:00 2001 From: Sean Hammond Date: Tue, 11 Jun 2024 20:03:12 +0100 Subject: [PATCH 01/12] Add theme, Python version, siteurl and feed_domain to GitHub Pages deployment workflow Add theme, Python version, siteurl and feed_domain support to the reusable GitHub Actions workflow for deploying a Pelican site to GitHub Pages: 1. Add a new `theme` option to the workflow that callers can use to specify an external theme to be checked out and used 2. Add a new `python` option to the workflow that callers can use to specify the Python version, in case they need to build their site with a particular version of Python 3. Pass `--extra-settings FEED_DOMAIN='"${{ steps.pages.outputs.base_url }}"'` to the `pelican` command to set the value of Pelican's `FEED_DOMAIN` setting for feed URLs. 4. Add a `feed_domain` input to the workflow so that users can override the feed domain if they need to. 5. Add a `siteurl` input to the workflow so that users can override the site URL if they need to. 6. Add a note to the docs about GitHub Pages generating http:// URLs for https:// sites, and how to fix it 7. Some light editing of the docs for the workflow --- .github/workflows/github_pages.yml | 43 +++++++++++++-- docs/tips.rst | 88 +++++++++++++++++++++--------- 2 files changed, 100 insertions(+), 31 deletions(-) diff --git a/.github/workflows/github_pages.yml b/.github/workflows/github_pages.yml index f4a01b92..efe6959c 100644 --- a/.github/workflows/github_pages.yml +++ b/.github/workflows/github_pages.yml @@ -17,6 +17,26 @@ on: default: "output/" description: "Where to output the generated files (`pelican`'s `--output` option)" type: string + theme: + required: false + default: "" + description: "The GitHub repo URL of a custom theme to use, for example: 'https://github.com/seanh/sidecar.git'" + type: string + python: + required: false + default: "3.12" + description: "The version of Python to use, for example: '3.12' (to use the most recent version of Python 3.12, this is faster) or '3.12.1' (to use an exact version, slower)" + type: string + siteurl: + required: false + default: "" + description: "The base URL of your web site (Pelican's SITEURL setting). If not passed this will default to the URL of your GitHub Pages site, which is correct in most cases." + type: string + feed_domain: + required: false + default: "" + description: "The domain to be prepended to feed URLs (Pelican's FEED_DOMAIN setting). If not passed this will default to the URL of your GitHub Pages site, which is correct in most cases." + type: string permissions: contents: read pages: write @@ -33,18 +53,31 @@ jobs: - name: Set up Python uses: actions/setup-python@v4 with: - python-version: "3.11" + python-version: ${{ inputs.python }} + - name: Checkout theme + if: ${{ inputs.theme }} + run: git clone '${{ inputs.theme }}' .theme - name: Configure GitHub Pages id: pages uses: actions/configure-pages@v3 - name: Install requirements run: pip install ${{ inputs.requirements }} - name: Build Pelican site + shell: python run: | - pelican \ - --settings "${{ inputs.settings }}" \ - --extra-settings SITEURL='"${{ steps.pages.outputs.base_url }}"' \ - --output "${{ inputs.output-path }}" + import subprocess + + cmd = "pelican" + cmd += " --settings ${{ inputs.settings }}" + cmd += " --extra-settings" + cmd += """ SITEURL='"${{ inputs.siteurl || steps.pages.outputs.base_url }}"'""" + cmd += """ FEED_DOMAIN='"${{ inputs.feed_domain || steps.pages.outputs.base_url }}"'""" + cmd += " --output ${{ inputs.output-path }}" + + if "${{ inputs.theme }}": + cmd += " --theme-path .theme" + + subprocess.run(cmd, shell=True, check=True) - name: Fix permissions run: | chmod -c -R +rX "${{ inputs.output-path }}" | while read line; do diff --git a/docs/tips.rst b/docs/tips.rst index 3344900d..5d75e4fb 100644 --- a/docs/tips.rst +++ b/docs/tips.rst @@ -163,8 +163,8 @@ Pelican-powered sites can be published to GitHub Pages via a `custom workflow Notes: -* You don't need to set ``SITEURL`` in your Pelican settings: the workflow will - set it for you +* You don't need to set ``SITEURL`` or ``FEED_DOMAIN`` in your Pelican + settings: the workflow will set them correctly for you * You don't need to commit your ``--output`` / ``OUTPUT_PATH`` directory (``output/``) to git: the workflow will run ``pelican`` to build the output @@ -174,36 +174,72 @@ See `GitHub's docs about reusable workflows Date: Mon, 17 Jun 2024 16:38:10 +0100 Subject: [PATCH 02/12] Add Dependabot to GitHub Actions workflow docs --- docs/tips.rst | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/docs/tips.rst b/docs/tips.rst index 5d75e4fb..338dbe1f 100644 --- a/docs/tips.rst +++ b/docs/tips.rst @@ -152,6 +152,25 @@ Pelican-powered sites can be published to GitHub Pages via a `custom workflow with: settings: "publishconf.py" + You may want to replace the ``@master`` with the ID of a specific commit in + this repo in order to pin the version of the reusable workflow that you're using: + ``uses: getpelican/pelican/.github/workflows/github_pages.yml@``. + If you do this you might want to get Dependabot to send you automated pull + requests to update that commit ID whenever new versions of this workflow are + published, like so: + + .. code-block:: yaml + + # .github/dependabot.yml + version: 2 + updates: + - package-ecosystem: "github-actions" + directory: "/" + schedule: + interval: "monthly" + + See `GitHub's docs about using Dependabot to keep your actions up to date `_. + 3. Go to the **Actions** tab in your repo (``https://github.com///actions``) and you should see a **Deploy to GitHub Pages** action running. From 50f77b42b2acfffbb3451aa15374726a96c1c8eb Mon Sep 17 00:00:00 2001 From: Justin Mayer Date: Mon, 17 Jun 2024 20:36:18 +0200 Subject: [PATCH 03/12] Add CODEOWNERS file to project --- .github/CODEOWNERS | 1 + 1 file changed, 1 insertion(+) create mode 100644 .github/CODEOWNERS diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 00000000..0fbd850c --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1 @@ +.github/workflows/github_pages.yml @seanh From d03ae2a41fc813f8b8ee0d8df46d8b9e18bb0d20 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Mon, 17 Jun 2024 11:44:06 +0000 Subject: [PATCH 04/12] Bump actions/upload-pages-artifact from 2 to 3 Bumps [actions/upload-pages-artifact](https://github.com/actions/upload-pages-artifact) from 2 to 3. - [Release notes](https://github.com/actions/upload-pages-artifact/releases) - [Commits](https://github.com/actions/upload-pages-artifact/compare/v2...v3) --- updated-dependencies: - dependency-name: actions/upload-pages-artifact dependency-type: direct:production update-type: version-update:semver-major ... Signed-off-by: dependabot[bot] --- .github/workflows/github_pages.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/github_pages.yml b/.github/workflows/github_pages.yml index efe6959c..d8a18de3 100644 --- a/.github/workflows/github_pages.yml +++ b/.github/workflows/github_pages.yml @@ -84,7 +84,7 @@ jobs: echo "::warning title=Invalid file permissions automatically fixed::$line" done - name: Upload artifact - uses: actions/upload-pages-artifact@v2 + uses: actions/upload-pages-artifact@v3 with: path: ${{ inputs.output-path }} deploy: From 750a1f8bfaf4d14aafd398976c55ecab332e3001 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Mon, 17 Jun 2024 18:44:01 +0000 Subject: [PATCH 05/12] Bump actions/configure-pages from 3 to 5 Bumps [actions/configure-pages](https://github.com/actions/configure-pages) from 3 to 5. - [Release notes](https://github.com/actions/configure-pages/releases) - [Commits](https://github.com/actions/configure-pages/compare/v3...v5) --- updated-dependencies: - dependency-name: actions/configure-pages dependency-type: direct:production update-type: version-update:semver-major ... Signed-off-by: dependabot[bot] --- .github/workflows/github_pages.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/github_pages.yml b/.github/workflows/github_pages.yml index d8a18de3..0e9eab77 100644 --- a/.github/workflows/github_pages.yml +++ b/.github/workflows/github_pages.yml @@ -59,7 +59,7 @@ jobs: run: git clone '${{ inputs.theme }}' .theme - name: Configure GitHub Pages id: pages - uses: actions/configure-pages@v3 + uses: actions/configure-pages@v5 - name: Install requirements run: pip install ${{ inputs.requirements }} - name: Build Pelican site From 487877f206ff124278fc53be22eb00bafc3708f4 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Mon, 17 Jun 2024 11:44:10 +0000 Subject: [PATCH 06/12] Bump actions/deploy-pages from 2 to 4 Bumps [actions/deploy-pages](https://github.com/actions/deploy-pages) from 2 to 4. - [Release notes](https://github.com/actions/deploy-pages/releases) - [Commits](https://github.com/actions/deploy-pages/compare/v2...v4) --- updated-dependencies: - dependency-name: actions/deploy-pages dependency-type: direct:production update-type: version-update:semver-major ... Signed-off-by: dependabot[bot] --- .github/workflows/github_pages.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/github_pages.yml b/.github/workflows/github_pages.yml index 0e9eab77..427ad96d 100644 --- a/.github/workflows/github_pages.yml +++ b/.github/workflows/github_pages.yml @@ -96,4 +96,4 @@ jobs: steps: - name: Deploy to GitHub Pages id: deployment - uses: actions/deploy-pages@v2 + uses: actions/deploy-pages@v4 From 617aba077f1692925dc07abaf61999e624ac922a Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Mon, 17 Jun 2024 18:44:11 +0000 Subject: [PATCH 07/12] Bump actions/setup-python from 4 to 5 Bumps [actions/setup-python](https://github.com/actions/setup-python) from 4 to 5. - [Release notes](https://github.com/actions/setup-python/releases) - [Commits](https://github.com/actions/setup-python/compare/v4...v5) --- updated-dependencies: - dependency-name: actions/setup-python dependency-type: direct:production update-type: version-update:semver-major ... Signed-off-by: dependabot[bot] --- .github/workflows/github_pages.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/github_pages.yml b/.github/workflows/github_pages.yml index 427ad96d..e7f7b59a 100644 --- a/.github/workflows/github_pages.yml +++ b/.github/workflows/github_pages.yml @@ -51,7 +51,7 @@ jobs: - name: Checkout uses: actions/checkout@v4 - name: Set up Python - uses: actions/setup-python@v4 + uses: actions/setup-python@v5 with: python-version: ${{ inputs.python }} - name: Checkout theme From 853e9e6b8a479b99217ca0f9928012eca90a7ecd Mon Sep 17 00:00:00 2001 From: Sean Hammond Date: Mon, 17 Jun 2024 20:46:28 +0100 Subject: [PATCH 08/12] Document that feed_domain is not required --- docs/tips.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tips.rst b/docs/tips.rst index 338dbe1f..c86a12f4 100644 --- a/docs/tips.rst +++ b/docs/tips.rst @@ -240,7 +240,7 @@ Here's the complete list of workflow inputs: | | | Pages site, which is correct in most | | | | | | cases. | | | +------------------+----------+--------------------------------------------+--------+---------------+ -| ``feed_domain`` | | The domain to be prepended to feed URLs | string | The URL of | +| ``feed_domain`` | No | The domain to be prepended to feed URLs | string | The URL of | | | | (Pelican's ``FEED_DOMAIN`` setting). If | | your GitHub | | | | not passed this will default to the URL of | | Pages site. | | | | your GitHub Pages site, which is correct | | | From 05535c7d6c274dc6e3560b70e98f73bc6d01e052 Mon Sep 17 00:00:00 2001 From: Justin Mayer Date: Mon, 17 Jun 2024 22:19:21 +0200 Subject: [PATCH 09/12] Docs: GitHub Pages workflow is now supported --- .github/workflows/github_pages.yml | 2 +- docs/tips.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/github_pages.yml b/.github/workflows/github_pages.yml index e7f7b59a..48ebb2d0 100644 --- a/.github/workflows/github_pages.yml +++ b/.github/workflows/github_pages.yml @@ -1,4 +1,4 @@ -# Workflow for publishing to GitHub Pages. **NO OFFICIAL SUPPORT PROVIDED.** +# Workflow for publishing to GitHub Pages. name: Deploy to GitHub Pages on: workflow_call: diff --git a/docs/tips.rst b/docs/tips.rst index 338dbe1f..746b5e43 100644 --- a/docs/tips.rst +++ b/docs/tips.rst @@ -128,7 +128,7 @@ Publishing to GitHub Pages Using a Custom GitHub Actions Workflow Pelican-powered sites can be published to GitHub Pages via a `custom workflow `_. -**No official support is provided** for this community-submitted workflow. To use it: +To use it: 1. Enable GitHub Pages in your repo: go to **Settings → Pages** and choose **GitHub Actions** for the **Source** setting. From 993c75103b7fccebb33dc0a148a4b9be42373d54 Mon Sep 17 00:00:00 2001 From: Justin Mayer Date: Tue, 18 Jun 2024 09:04:59 +0200 Subject: [PATCH 10/12] Generate social cards in Sphinx documentation Without `matplotlib` installed, Sphinx output says that social cards cannot be generated. --- requirements/docs.pip | 1 + 1 file changed, 1 insertion(+) diff --git a/requirements/docs.pip b/requirements/docs.pip index 7b0f37cc..4c16c84a 100644 --- a/requirements/docs.pip +++ b/requirements/docs.pip @@ -2,4 +2,5 @@ sphinx sphinxext-opengraph furo==2023.9.10 livereload +matplotlib tomli;python_version<"3.11" From 49723e6daf8caf6c46ab6cb58715dfe6b7e4a40d Mon Sep 17 00:00:00 2001 From: Justin Mayer Date: Tue, 18 Jun 2024 09:08:45 +0200 Subject: [PATCH 11/12] Docs: Remove `ifconfig` Sphinx extension Originally added in #815, something about this seems to be causing an obscure ReadTheDocs build error. --- docs/conf.py | 1 - docs/index.rst | 9 --------- 2 files changed, 10 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 8f14a018..b812ee4c 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -21,7 +21,6 @@ with open("../pyproject.toml", "rb") as f: templates_path = ["_templates"] extensions = [ "sphinx.ext.autodoc", - "sphinx.ext.ifconfig", "sphinx.ext.extlinks", "sphinxext.opengraph", ] diff --git a/docs/index.rst b/docs/index.rst index 60591482..159ea3be 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,15 +1,6 @@ Pelican |release| ================= - -.. ifconfig:: release.endswith('.dev') - - .. warning:: - - This documentation is for the version of Pelican currently under - development. Were you looking for version |last_stable| documentation? - - Pelican is a static site generator, written in Python_. Highlights include: * Write your content directly with your editor of choice in reStructuredText_ From 5171631dec562f8033388b52f0690aa0381bf170 Mon Sep 17 00:00:00 2001 From: Tomasz Wojdat Date: Wed, 19 Jun 2024 00:11:28 +0200 Subject: [PATCH 12/12] chore: update URLs of GitHub Ribbons Old URLs are no longer active. New ones were taken from GitHub blog: https://github.blog/2008-12-19-github-ribbons/ Also update output in functional tests. --- pelican/tests/output/custom/a-markdown-powered-article.html | 2 +- pelican/tests/output/custom/archives.html | 2 +- pelican/tests/output/custom/article-1.html | 2 +- pelican/tests/output/custom/article-2.html | 2 +- pelican/tests/output/custom/article-3.html | 2 +- pelican/tests/output/custom/author/alexis-metaireau.html | 2 +- pelican/tests/output/custom/author/alexis-metaireau2.html | 2 +- pelican/tests/output/custom/author/alexis-metaireau3.html | 2 +- pelican/tests/output/custom/authors.html | 2 +- pelican/tests/output/custom/categories.html | 2 +- pelican/tests/output/custom/category/bar.html | 2 +- pelican/tests/output/custom/category/cat1.html | 2 +- pelican/tests/output/custom/category/misc.html | 2 +- pelican/tests/output/custom/category/yeah.html | 2 +- .../output/custom/drafts/a-draft-article-without-date.html | 2 +- pelican/tests/output/custom/drafts/a-draft-article.html | 2 +- pelican/tests/output/custom/filename_metadata-example.html | 2 +- pelican/tests/output/custom/index.html | 2 +- pelican/tests/output/custom/index2.html | 2 +- pelican/tests/output/custom/index3.html | 2 +- pelican/tests/output/custom/jinja2_template.html | 2 +- pelican/tests/output/custom/oh-yeah-fr.html | 2 +- pelican/tests/output/custom/oh-yeah.html | 2 +- pelican/tests/output/custom/override/index.html | 2 +- .../tests/output/custom/pages/this-is-a-test-hidden-page.html | 2 +- pelican/tests/output/custom/pages/this-is-a-test-page.html | 2 +- pelican/tests/output/custom/second-article-fr.html | 2 +- pelican/tests/output/custom/second-article.html | 2 +- pelican/tests/output/custom/tag/bar.html | 2 +- pelican/tests/output/custom/tag/baz.html | 2 +- pelican/tests/output/custom/tag/foo.html | 2 +- pelican/tests/output/custom/tag/foobar.html | 2 +- pelican/tests/output/custom/tag/oh.html | 2 +- pelican/tests/output/custom/tag/yeah.html | 2 +- pelican/tests/output/custom/tags.html | 2 +- pelican/tests/output/custom/this-is-a-super-article.html | 2 +- pelican/tests/output/custom/unbelievable.html | 2 +- pelican/tests/output/custom_locale/archives.html | 2 +- .../tests/output/custom_locale/author/alexis-metaireau.html | 2 +- .../tests/output/custom_locale/author/alexis-metaireau2.html | 2 +- .../tests/output/custom_locale/author/alexis-metaireau3.html | 2 +- pelican/tests/output/custom_locale/authors.html | 2 +- pelican/tests/output/custom_locale/categories.html | 2 +- pelican/tests/output/custom_locale/category/bar.html | 2 +- pelican/tests/output/custom_locale/category/cat1.html | 2 +- pelican/tests/output/custom_locale/category/misc.html | 2 +- pelican/tests/output/custom_locale/category/yeah.html | 2 +- .../custom_locale/drafts/a-draft-article-without-date.html | 2 +- .../tests/output/custom_locale/drafts/a-draft-article.html | 2 +- pelican/tests/output/custom_locale/index.html | 2 +- pelican/tests/output/custom_locale/index2.html | 2 +- pelican/tests/output/custom_locale/index3.html | 2 +- pelican/tests/output/custom_locale/jinja2_template.html | 2 +- pelican/tests/output/custom_locale/oh-yeah-fr.html | 2 +- pelican/tests/output/custom_locale/override/index.html | 2 +- .../custom_locale/pages/this-is-a-test-hidden-page.html | 2 +- .../tests/output/custom_locale/pages/this-is-a-test-page.html | 2 +- .../posts/2010/décembre/02/this-is-a-super-article/index.html | 2 +- .../posts/2010/octobre/15/unbelievable/index.html | 2 +- .../custom_locale/posts/2010/octobre/20/oh-yeah/index.html | 2 +- .../posts/2011/avril/20/a-markdown-powered-article/index.html | 2 +- .../custom_locale/posts/2011/février/17/article-1/index.html | 2 +- .../custom_locale/posts/2011/février/17/article-2/index.html | 2 +- .../custom_locale/posts/2011/février/17/article-3/index.html | 2 +- .../posts/2012/février/29/second-article/index.html | 2 +- .../2012/novembre/30/filename_metadata-example/index.html | 2 +- pelican/tests/output/custom_locale/second-article-fr.html | 2 +- pelican/tests/output/custom_locale/tag/bar.html | 2 +- pelican/tests/output/custom_locale/tag/baz.html | 2 +- pelican/tests/output/custom_locale/tag/foo.html | 2 +- pelican/tests/output/custom_locale/tag/foobar.html | 2 +- pelican/tests/output/custom_locale/tag/oh.html | 2 +- pelican/tests/output/custom_locale/tag/yeah.html | 2 +- pelican/tests/output/custom_locale/tags.html | 2 +- pelican/themes/notmyidea/templates/github.html | 4 ++-- 75 files changed, 76 insertions(+), 76 deletions(-) diff --git a/pelican/tests/output/custom/a-markdown-powered-article.html b/pelican/tests/output/custom/a-markdown-powered-article.html index 1cee58f6..b8359a6d 100644 --- a/pelican/tests/output/custom/a-markdown-powered-article.html +++ b/pelican/tests/output/custom/a-markdown-powered-article.html @@ -13,7 +13,7 @@ - Fork me on GitHub + Fork me on GitHub