Add theme, Python version, and feed domain to GitHub Pages deployment workflow #3330
Conversation
| - name: Checkout theme | ||
| if: ${{ inputs.theme }} | ||
| run: git clone '${{ inputs.theme }}' .theme |
There was a problem hiding this comment.
This should work for any Git repo URL, not just GitHub ones
.github/workflows/github_pages.yml
Outdated
| import subprocess | ||
|
|
||
| cmd = "pelican" | ||
| cmd += " --settings ${{ inputs.settings }}" | ||
| cmd += " --extra-settings" | ||
| cmd += """ SITEURL='"${{ steps.pages.outputs.base_url }}"'""" | ||
| cmd += """ FEED_DOMAIN='"${{ steps.pages.outputs.origin }}"'""" | ||
| cmd += " --output ${{ inputs.output-path }}" | ||
|
|
||
| if "${{ inputs.theme }}": | ||
| cmd += " --theme-path .theme" | ||
|
|
||
| subprocess.run(cmd, shell=True, check=True) |
There was a problem hiding this comment.
This needs to pass the --theme-path to pelican only if the caller workflow passed the theme option. I'm dropping into Python as the shell here, this simple script is just complex enough that writing it in Bash would be a pain.
Normally I would use a list (rather than string concatenation) and would not use shell=True, but I couldn't get the quoting around SITEURL='"${{ steps.pages.outputs.base_url }}"' to work properly (kept getting invalid JSON errors from Pelican) until I changed this to string concatenation and shell=True 🤷♂️
.github/workflows/github_pages.yml
Outdated
| cmd += """ SITEURL='"${{ steps.pages.outputs.base_url }}"'""" | ||
| cmd += """ FEED_DOMAIN='"${{ steps.pages.outputs.origin }}"'""" |
There was a problem hiding this comment.
Adding the FEED_DOMAIN setting, along with the SITEURL setting that was already here.
GitHub Actions knows the URL of the GitHub Pages site that is being deployed to, so there's no need for the user to supply the SITEURL and FEED_DOMAIN settings, the workflow can inject the correct values automatically.
${{ steps.pages.outputs.base_url }} is the base URL that the site is being deployed to, appropriate for the SITEURL setting. For example "https://octocat.github.io" (for a user or organization site) or "https://octocat.github.io/my-repo" for a project site. If the user has set up a custom domain for GitHub Pages it'll use that, e.g. "https://www.example.com" or "https://www.example.com/my-repo".
${{ steps.pages.outputs.origin }} is the origin part of the site URL, for example "https://octocat.github.io" or "https://www.example.com/my-repo" (no /my-repo at the end for project sites). I believe this is correct for FEED_DOMAIN?
(These variables come from the output's of GitHub's configure-pages action, they're documented here: https://github.com/actions/configure-pages/blob/e1bedb377708461b49c882870df192bdec04b996/action.yml#L22-L30.)
There was a problem hiding this comment.
I added the FEED_DOMAIN setting for the use case in which the domain used for the web site (e.g., example.com) is different than the domain used for serving the feed(s) (e.g., feeds.example.com). If, on the other hand, both the web site and the feeds are served from the same domain, then the appropriate setting should be: FEED_DOMAIN = SITEURL
Does that help clarify?
There was a problem hiding this comment.
Got it, thanks.
Ok, I've changed it to set FEED_DOMAIN to the same URL of the GitHub Pages site as it sets SITEURL to. I've tested this on two of my own Pelican sites, one a user site and one a project site (project sites are deployed to sub-folders of the user's domain) and it seems to work correctly.
I also added an optional feed_domain workflow input so that users can override the default FEED_DOMAIN in case they're somehow deploying their feeds to a different domain.
Also added a siteurl input to override the default SITEURL. I'm not sure whether there's a use-case for setting SITEURL manually with this workflow but I put it in just for good measure.
I also added a note to the docs about GitHub Pages generating http:// URLs for https:// sites and how to fix it.
…ployment 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
seanh
force-pushed
the
gha-theme-support
branch
2 times, most recently
from
a3ad621 to
e46595c
Compare
| 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@<COMMIT_ID>``. | ||
| 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 <https://docs.github.com/en/code-security/dependabot/working-with-dependabot/keeping-your-actions-up-to-date-with-dependabot>`_. |
There was a problem hiding this comment.
Also added this note about pinning the workflow version and then using Dependabot to keep it up to date.
justinmayer
changed the title
|
@justinmayer is the readthedocs integration broken? I noticed that the documentation changes in this PR haven't appeared over in the docs and it looks like the docs haven't had a build in several months |
|
(I was assuming RTD builds should be triggered automatically when a commit is merged into |
|
@seanh: ReadTheDocs is supposed to automatically trigger a build when a commit lands in the primary branch, but the web-hook constantly gets out-of-sync for who-knows-what-reason, which silently breaks those alleged automatic builds. And then, when I tried a manual build just now, I see this inscrutable error: https://readthedocs.org/projects/pelican/builds/24724000/ Any idea how to resolve that error? (I find ReadTheDocs to be very frustrating.) |
Yeah readthedocs/Sphinx can be a bit fragile and complicated. Sphinx has a lot of powerful features that're useful for maintaining large documents and that other documentation systems lack. But I think it's a bit heavy for small projects. Readthedocs does have support for MkDocs which might be simpler and more robust.
I may be able to look into it at some point in the next several days... The error appears to be coming from |
|
@seanh: Thank you for taking a quick look. Via the PR linked above, I removed the |
Add theme, Python version and feed domain support to the reusable GitHub Actions workflow for deploying a Pelican site to GitHub Pages:
Add a new
themeoption to the workflow that callers can use to specify an external theme to be checked out and usedAdd a new
pythonoption 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 PythonPass
--extra-settings FEED_DOMAIN='"${{ steps.pages.outputs.origin }}"'to thepelicancommand to set the value of Pelican'sFEED_DOMAINsetting for feed URLs.