From 4b65c9c33c1fa0bd64b916e5ad5524756685fee0 Mon Sep 17 00:00:00 2001 From: Richard Darst Date: Sat, 9 Sep 2023 13:27:18 +0300 Subject: [PATCH 1/5] .github/workflows/sphinx: add deployment permission --- .github/workflows/sphinx.yml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.github/workflows/sphinx.yml b/.github/workflows/sphinx.yml index 346291c..976bb1d 100644 --- a/.github/workflows/sphinx.yml +++ b/.github/workflows/sphinx.yml @@ -12,6 +12,9 @@ jobs: build-and-deploy: name: Build and gh-pages runs-on: ubuntu-latest + permissions: + contents: write + steps: # https://github.com/marketplace/actions/checkout - uses: actions/checkout@v2 From 13f081cab061704270f78af51db0aba15f69c010 Mon Sep 17 00:00:00 2001 From: Richard Darst Date: Mon, 11 Sep 2023 01:01:02 +0300 Subject: [PATCH 2/5] .github/workflows/sphinx: Update action - Use gh-pages-multibranch to simplify the multibranch stuff - Scope the write permission to only the deployment step - Overall simplify and document --- .github/workflows/sphinx.yml | 159 ++++++++++++++++++----------------- 1 file changed, 84 insertions(+), 75 deletions(-) diff --git a/.github/workflows/sphinx.yml b/.github/workflows/sphinx.yml index 976bb1d..118749b 100644 --- a/.github/workflows/sphinx.yml +++ b/.github/workflows/sphinx.yml @@ -1,54 +1,65 @@ -# From: https://github.com/rkdarst/sphinx-actions-test/blob/master/.github/workflows/sphinx-build.yml +# Deploy Sphinx. This could be shorter, but we also do some extra +# stuff. +# +# License: CC-0. This is the canonical location of this file, which +# you may want to link to anyway: +# https://github.com/coderefinery/sphinx-lesson-template/blob/main/.github/workflows/sphinx.yml + name: sphinx on: [push, pull_request] env: DEFAULT_BRANCH: "main" + # If these SPHINXOPTS are enabled, then be strict about the + # builds and fail on any warnings. #SPHINXOPTS: "-W --keep-going -T" - # ^-- If these SPHINXOPTS are enabled, then be strict about the builds and fail on any warnings + GENERATE_PDF: true # to enable, must be 'true' lowercase + MULTIBRANCH: true # same + jobs: - build-and-deploy: - name: Build and gh-pages + build: + name: Build runs-on: ubuntu-latest permissions: - contents: write + contents: read steps: # https://github.com/marketplace/actions/checkout - - uses: actions/checkout@v2 + - uses: actions/checkout@v4 with: fetch-depth: 0 lfs: true + # https://github.com/marketplace/actions/setup-python # ^-- This gives info on matrix testing. - name: Install Python - uses: actions/setup-python@v2 + uses: actions/setup-python@v4 with: - python-version: 3.8 - # https://docs.github.com/en/actions/guides/building-and-testing-python#caching-dependencies - # ^-- How to set up caching for pip on Ubuntu - - name: Cache pip - uses: actions/cache@v2 - with: - path: ~/.cache/pip - key: ${{ runner.os }}-pip-${{ hashFiles('requirements.txt') }} - restore-keys: | - ${{ runner.os }}-pip- - ${{ runner.os }}- + python-version: '3.11' + cache: 'pip' + # https://docs.github.com/en/actions/guides/building-and-testing-python#installing-dependencies # ^-- This gives info on installing dependencies with pip - name: Install dependencies run: | python -m pip install --upgrade pip pip install -r requirements.txt + + # Debug - name: Debugging information + env: + ref: ${{github.ref}} + event_name: ${{github.event_name}} + head_ref: ${{github.head_ref}} + base_ref: ${{github.base_ref}} run: | - echo "github.ref:" ${{github.ref}} - echo "github.event_name:" ${{github.event_name}} - echo "github.head_ref:" ${{github.head_ref}} - echo "github.base_ref:" ${{github.base_ref}} + echo "github.ref: ${ref}" + echo "github.event_name: ${event_name}" + echo "github.head_ref: ${head_ref}" + echo "github.base_ref: ${base_ref}" + echo "GENERATE_PDF: ${GENERATE_PDF}" set -x git rev-parse --abbrev-ref HEAD git branch @@ -61,7 +72,8 @@ jobs: # Build - uses: ammaraskar/sphinx-problem-matcher@master - - name: Build Sphinx docs + - name: Build Sphinx docs (dirhtml) + # SPHINXOPTS used via environment variables run: | make dirhtml # This fixes broken copy button icons, as explained in @@ -73,60 +85,31 @@ jobs: # https://github.com/readthedocs/sphinx_rtd_theme/pull/1025 sed -i 's/url_root="#"/url_root=""/' _build/dirhtml/index.html || true + # PDF if requested + - name: Generate PDF + if: ${{ env.GENERATE_PDF == 'true' }} + run: | + pip install https://github.com/rkdarst/sphinx_pyppeteer_builder/archive/refs/heads/main.zip + make pyppeteer + mv _build/pyppeteer/*.pdf _build/dirhtml/_static/lesson.pdf - # The following supports building all branches and combining on - # gh-pages - - # Clone and set up the old gh-pages branch - - name: Clone old gh-pages + # Stage all deployed assets in _gh-pages/ for simplicity, and to + # prepare to do a multi-branch deployment. + - name: Copy deployment data to _gh-pages/ if: ${{ github.event_name == 'push' }} - run: | - set -x - git fetch - ( git branch gh-pages remotes/origin/gh-pages && git clone . --branch=gh-pages _gh-pages/ ) || mkdir _gh-pages - rm -rf _gh-pages/.git/ - mkdir -p _gh-pages/branch/ - # If a push and default branch, copy build to _gh-pages/ as the "main" - # deployment. - - name: Copy new build (default branch) - if: | - contains(github.event_name, 'push') && - contains(github.ref, env.DEFAULT_BRANCH) - run: | - set -x - # Delete everything under _gh-pages/ that is from the - # primary branch deployment. Eicludes the other branches - # _gh-pages/branch-* paths, and not including - # _gh-pages itself. - find _gh-pages/ -mindepth 1 ! -path '_gh-pages/branch*' -delete + run: rsync -a _build/dirhtml/ _gh-pages/ - # If a push and not on default branch, then copy the build to - # _gh-pages/branch/$brname (transforming '/' into '--') - - name: Copy new build (branch) - if: | - contains(github.event_name, 'push') && - !contains(github.ref, env.DEFAULT_BRANCH) - run: | - set -x - #brname=$(git rev-parse --abbrev-ref HEAD) - brname="${{github.ref}}" - brname="${brname##refs/heads/}" - brdir=${brname//\//--} # replace '/' with '--' - rm -rf _gh-pages/branch/${brdir} - rsync -a _build/dirhtml/ _gh-pages/branch/${brdir} - # Go through each branch in _gh-pages/branch/, if it's not a - # ref, then delete it. - - name: Delete old feature branches - if: ${{ github.event_name == 'push' }} - run: | - set -x - for brdir in `ls _gh-pages/branch/` ; do - brname=${brdir//--/\/} # replace '--' with '/' - if ! git show-ref remotes/origin/$brname ; then - echo "Removing $brdir" - rm -r _gh-pages/branch/$brdir/ - fi - done + + # Use gh-pages-multibranch to multiplex different branches into + # one deployment. See + # https://github.com/coderefinery/gh-pages-multibranch + - name: gh-pages multibranch + uses: coderefinery/gh-pages-multibranch@main + if: ${{ github.event_name == 'push' && env.MULTIBRANCH == 'true' }} + with: + directory: _gh-pages/ + default_branch: ${{ env.DEFAULT_BRANCH }} + publish_branch: gh-pages # Add the .nojekyll file - name: nojekyll @@ -134,12 +117,38 @@ jobs: run: | touch _gh-pages/.nojekyll + # Save artifact for the next step. + - uses: actions/upload-artifact@master + with: + name: gh-pages-build + path: _gh-pages/ + + # Deploy in a separate job so that write permissions are restricted + # to the minimum steps. + deploy: + name: Deploy + runs-on: ubuntu-latest + needs: build + permissions: + contents: write + + steps: + - uses: actions/download-artifact@v3 + with: + name: gh-pages-build + path: _gh-pages/ + + # As of 2023, we could publish to pages via a Deployment. This + # isn't done yet to give it time to stabilize (out of beta), and + # also having a gh-pages branch to check out is rather + # convenient. + # Deploy # https://github.com/peaceiris/actions-gh-pages - name: Deploy uses: peaceiris/actions-gh-pages@v3 if: ${{ github.event_name == 'push' }} - #if: ${{ success() && github.event_name == 'push' && github.ref == 'refs/heads/$defaultBranch' }} + #if: ${{ success() && github.event_name == 'push' && github.ref == 'refs/heads/$DEFAULT_BRANCH' }} with: publish_branch: gh-pages github_token: ${{ secrets.GITHUB_TOKEN }} From 5044dbcde0da79740bcb25079142fabc72a9e94b Mon Sep 17 00:00:00 2001 From: Richard Darst Date: Wed, 13 Sep 2023 19:48:43 +0300 Subject: [PATCH 3/5] .github/workflows/sphinx: Bugfixes from git-intro --- .github/workflows/sphinx.yml | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/.github/workflows/sphinx.yml b/.github/workflows/sphinx.yml index 118749b..d7d2f43 100644 --- a/.github/workflows/sphinx.yml +++ b/.github/workflows/sphinx.yml @@ -15,7 +15,8 @@ env: # builds and fail on any warnings. #SPHINXOPTS: "-W --keep-going -T" GENERATE_PDF: true # to enable, must be 'true' lowercase - MULTIBRANCH: true # same + PDF_FILENAME: lesson.pdf + MULTIBRANCH: true # to enable, must be 'true' lowercase jobs: @@ -91,7 +92,7 @@ jobs: run: | pip install https://github.com/rkdarst/sphinx_pyppeteer_builder/archive/refs/heads/main.zip make pyppeteer - mv _build/pyppeteer/*.pdf _build/dirhtml/_static/lesson.pdf + mv _build/pyppeteer/*.pdf _build/dirhtml/_static/${PDF_FILENAME}.pdf # Stage all deployed assets in _gh-pages/ for simplicity, and to # prepare to do a multi-branch deployment. @@ -119,6 +120,7 @@ jobs: # Save artifact for the next step. - uses: actions/upload-artifact@master + if: ${{ github.event_name == 'push' }} with: name: gh-pages-build path: _gh-pages/ @@ -129,11 +131,14 @@ jobs: name: Deploy runs-on: ubuntu-latest needs: build + # This if can't use the env context - find better way later. + if: ${{ github.event_name == 'push' }} permissions: contents: write steps: - uses: actions/download-artifact@v3 + if: ${{ github.event_name == 'push' && ( env.MULTIBRANCH == 'true' || github.ref == format('refs/heads/{0}', env.DEFAULT_BRANCH )) }} with: name: gh-pages-build path: _gh-pages/ @@ -147,8 +152,7 @@ jobs: # https://github.com/peaceiris/actions-gh-pages - name: Deploy uses: peaceiris/actions-gh-pages@v3 - if: ${{ github.event_name == 'push' }} - #if: ${{ success() && github.event_name == 'push' && github.ref == 'refs/heads/$DEFAULT_BRANCH' }} + if: ${{ github.event_name == 'push' && ( env.MULTIBRANCH == 'true' || github.ref == format('refs/heads/{0}', env.DEFAULT_BRANCH )) }} with: publish_branch: gh-pages github_token: ${{ secrets.GITHUB_TOKEN }} From de33b951015bcb1b5242dfb98aeebde43069e2fb Mon Sep 17 00:00:00 2001 From: Richard Darst Date: Fri, 22 Sep 2023 12:16:16 +0300 Subject: [PATCH 4/5] .github/workflows/sphinx: remove _static/ from PDF lesson location --- .github/workflows/sphinx.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/sphinx.yml b/.github/workflows/sphinx.yml index d7d2f43..b8c883c 100644 --- a/.github/workflows/sphinx.yml +++ b/.github/workflows/sphinx.yml @@ -92,7 +92,7 @@ jobs: run: | pip install https://github.com/rkdarst/sphinx_pyppeteer_builder/archive/refs/heads/main.zip make pyppeteer - mv _build/pyppeteer/*.pdf _build/dirhtml/_static/${PDF_FILENAME}.pdf + mv _build/pyppeteer/*.pdf _build/dirhtml/${PDF_FILENAME} # Stage all deployed assets in _gh-pages/ for simplicity, and to # prepare to do a multi-branch deployment. From a9b5889ed0fa5b6e753cf99ea939e57231c50f19 Mon Sep 17 00:00:00 2001 From: Richard Darst Date: Sun, 8 Oct 2023 22:41:10 +0300 Subject: [PATCH 5/5] .github/workflows/sphinx: Add singlehtml generation --- .github/workflows/sphinx.yml | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/.github/workflows/sphinx.yml b/.github/workflows/sphinx.yml index b8c883c..ef56675 100644 --- a/.github/workflows/sphinx.yml +++ b/.github/workflows/sphinx.yml @@ -14,7 +14,8 @@ env: # If these SPHINXOPTS are enabled, then be strict about the # builds and fail on any warnings. #SPHINXOPTS: "-W --keep-going -T" - GENERATE_PDF: true # to enable, must be 'true' lowercase + GENERATE_PDF: true # to enable, must be 'true' lowercase + GENERATE_SINGLEHTML: true # to enable, must be 'true' lowercase PDF_FILENAME: lesson.pdf MULTIBRANCH: true # to enable, must be 'true' lowercase @@ -61,6 +62,7 @@ jobs: echo "github.head_ref: ${head_ref}" echo "github.base_ref: ${base_ref}" echo "GENERATE_PDF: ${GENERATE_PDF}" + echo "GENERATE_SINGLEHTML: ${GENERATE_SINGLEHTML}" set -x git rev-parse --abbrev-ref HEAD git branch @@ -86,6 +88,13 @@ jobs: # https://github.com/readthedocs/sphinx_rtd_theme/pull/1025 sed -i 's/url_root="#"/url_root=""/' _build/dirhtml/index.html || true + # singlehtml + - name: Generate singlehtml + if: ${{ env.GENERATE_SINGLEHTML == 'true' }} + run: | + make singlehtml + mv _build/singlehtml/ _build/dirhtml/singlehtml/ + # PDF if requested - name: Generate PDF if: ${{ env.GENERATE_PDF == 'true' }}