Merge pull request #633 from dalito/issue625-docs-action

Fix docs action

.github/workflows/docs.yml

@@ -2,15 +2,19 @@
 name: Docs - build & deploy
 on:
   push:
-    branches: [master]
+    tags:
-  workflow_dispatch:
+      # for versions before 1.0.0
-    inputs:
+      - '[0-9]+.[0-9]+'
-      ref:
+      # after 1.0.0
-        description: "The commit SHA, tag, or branch to publish. Uses the default branch if not specified."
+      - '[0-9]+.[0-9]+.[0-9]+'
-        default: ""
+    branches: 
-        type: string
+      - master
+  pull_request:
+      branches:
+      - main
   release:
     types: [published]
+  workflow_dispatch:
 
 jobs:
   docs:
@@ -20,9 +24,11 @@ jobs:
       pages: write     # to deploy to Pages
       id-token: write  # to verify the deployment originates from an appropriate source
     runs-on: ubuntu-latest
-    if: github.ref == 'refs/heads/master' && github.repository_owner == 'EmilStenstrom'
+    # Only run in original repo (not in forks)
+    if: github.repository == 'EmilStenstrom/django-components'
     steps:
-      - uses: actions/checkout@v4
+      - name: Checkout
+        uses: actions/checkout@v4
         with:
           fetch-depth: 0
       - name: Set up Python
@@ -39,34 +45,51 @@ jobs:
       - name: Create Virtual Environment
         run: hatch env create docs
 
-      - name: "Check for mkdocs build --strict"
-        # XXX Enable strict mode once docs are clean
-        run: |
-          hatch run docs:build
-          # hatch run docs:build --strict
-        # If pull request or not master branch and not a tag
-        if: github.event_name == 'pull_request' || (github.event_name == 'push' && github.ref != 'refs/heads/master' && !startsWith(github.ref, 'refs/tags/')) || github.event_name == 'workflow_dispatch'
-
       - name: Configure git
         run: |
           git config user.name github-actions
           git config user.email github-actions@github.com
 
-      - name: Deploy docs (dev)
+      - name: Print variables for debugging
-        if: github.event_name == 'push' && github.ref_name == 'master' && github.ref_type == 'branch'
+        # XXX this step may be removed
+        # https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/accessing-contextual-information-about-workflow-runs#github-context
+        run: |
+          # env vars used in this action
+          echo 'event_name  : ' ${{ github.event_name }}
+          echo 'event.action: ' ${{ github.event.action }}
+          echo 'ref         : ' ${{ github.ref }}
+          echo 'ref_name    : ' ${{ github.ref_name }}
+          echo 'ref_type    : ' ${{ github.ref_type }}
+          echo 'repository  : ' ${{ github.repository }}
+
+      # Conditions make sure to select the right step, depending on the job trigger.
+      # Only one of the steps below will run. The others will be skipped.
+
+      - name: Check docs in pull requests with strict mode
+        if: github.event_name == 'pull_request'
+        run: |
+          # XXX Enable strict mode once docs are clean
+          echo "Strict check of docs disabled."
+          # hatch run docs:build --strict
+
+      - name: Build & deploy "dev" docs for a new commit to master
+        if: github.event_name == 'push' && github.ref_type != 'tag'
         run: |
           export SHORT_SHA=$(echo "${GITHUB_SHA}" | cut -c1-7)
-          hatch run docs:mike deploy dev --update-aliases --title "dev (${SHORT_SHA})" --push --alias-type=redirect
+          hatch run docs:mike deploy --push --update-aliases --title "dev (${SHORT_SHA})" dev
 
-      - name: Deploy docs (tag)
+      - name: Build & deploy docs for a new tag
         if: github.ref_type == 'tag' && github.event_name == 'push'
         run: |
-          hatch run docs:mike deploy ${{ github.ref_name }} latest --push --update-aliases --alias-type=redirect
+          # XXX next line removes docs wrongly deployed under latest identifier; remove once latest is used only as alias
+          hatch run docs:mike delete --push latest
+          hatch run docs:mike deploy --push --update-aliases ${{ github.ref_name }} latest
           hatch run docs:mike set-default latest --push
 
-      - name: Deploy docs (Released published)
+      - name: Build & deploy docs for a new release
-        if: github.event_name == 'release' && github.event.action == 'published' && github.ref_type == 'tag'
+        if: github.event_name == 'release'
         run: |
-          # Version from tag, keep leading v, from github.ref workflow variable
+          # XXX next line removes docs wrongly deployed under latest identifier; remove once latest is used only as alias
-          hatch run docs:mike deploy ${{ github.ref_name }} latest --push --update-aliases --alias-type=redirect
+          hatch run docs:mike delete --push latest
+          hatch run docs:mike deploy --push --update-aliases ${{ github.ref_name }} latest
           hatch run docs:mike set-default latest --push

.github/workflows/publish-to-pypi.yml

@@ -12,7 +12,7 @@ on:
 jobs:
   build:
     runs-on: ubuntu-latest
-
+    if: github.repository == 'EmilStenstrom/django-components'
     steps:
       - name: Checkout the repo
         uses: actions/checkout@v2

mkdocs.yml

@@ -64,12 +64,13 @@ theme:
       toggle:
         icon: material/weather-sunny
         name: Switch to light mode
+    
 extra:
   version:
     provider: mike
     default:
-      - latest
       - dev
+    alias: true
   social:
     - icon: fontawesome/brands/github
       link: https://github.com/EmilStenstrom/django-components

requirements-docs.txt

@@ -23,21 +23,21 @@
 
 asgiref==3.8.1
     # via django
-babel==2.14.0
+babel==2.16.0
     # via
     #   mkdocs-git-revision-date-localized-plugin
     #   mkdocs-material
-black==24.3.0
+black==24.8.0
     # via hatch.envs.docs
-bracex==2.4
+bracex==2.5
     # via wcmatch
-cairocffi==1.6.1
+cairocffi==1.7.1
     # via cairosvg
 cairosvg==2.7.1
     # via mkdocs-material
-certifi==2024.7.4
+certifi==2024.8.30
     # via requests
-cffi==1.16.0
+cffi==1.17.0
     # via cairocffi
 charset-normalizer==3.3.2
     # via requests
@@ -48,7 +48,9 @@ click==8.1.7
     #   mkdocstrings
 colorama==0.4.6
     # via
+    #   click
     #   griffe
+    #   mkdocs
     #   mkdocs-material
 csscompressor==0.9.5
     # via mkdocs-minify-plugin
@@ -56,7 +58,7 @@ cssselect2==0.7.0
     # via cairosvg
 defusedxml==0.7.1
     # via cairosvg
-django==5.0.8
+django==5.1
     # via hatch.envs.docs
 ghp-import==2.1.0
     # via mkdocs
@@ -68,7 +70,7 @@ griffe==1.2.0
     # via mkdocstrings-python
 htmlmin2==0.1.13
     # via mkdocs-minify-plugin
-idna==3.7
+idna==3.8
     # via requests
 importlib-metadata==8.4.0
     # via mike
@@ -82,15 +84,14 @@ jinja2==3.1.4
     #   mkdocstrings
 jsmin==3.0.1
     # via mkdocs-minify-plugin
-markdown==3.5.2
+markdown==3.7
     # via
     #   mkdocs
     #   mkdocs-autorefs
     #   mkdocs-material
     #   mkdocstrings
-    #   mkdocstrings-python
     #   pymdown-extensions
-markdown-exec==1.8.0
+markdown-exec==1.9.3
     # via hatch.envs.docs
 markupsafe==2.1.5
     # via
@@ -99,8 +100,10 @@ markupsafe==2.1.5
     #   mkdocs-autorefs
     #   mkdocstrings
 mergedeep==1.3.4
-    # via mkdocs
+    # via
-mike==2.0.0
+    #   mkdocs
+    #   mkdocs-get-deps
+mike==2.1.3
     # via hatch.envs.docs
 mkdocs==1.6.1
     # via
@@ -116,21 +119,24 @@ mkdocs==1.6.1
     #   mkdocs-minify-plugin
     #   mkdocs-redirects
     #   mkdocstrings
-mkdocs-autorefs==1.0.1
+mkdocs-autorefs==1.1.0
     # via
     #   hatch.envs.docs
     #   mkdocstrings
+    #   mkdocstrings-python
 mkdocs-gen-files==0.5.0
     # via hatch.envs.docs
+mkdocs-get-deps==0.2.0
+    # via mkdocs
 mkdocs-git-authors-plugin==0.9.0
     # via hatch.envs.docs
 mkdocs-git-revision-date-localized-plugin==1.2.7
     # via hatch.envs.docs
-mkdocs-include-markdown-plugin==6.0.5
+mkdocs-include-markdown-plugin==6.2.2
     # via hatch.envs.docs
 mkdocs-literate-nav==0.6.1
     # via hatch.envs.docs
-mkdocs-material==9.5.16
+mkdocs-material==9.5.34
     # via hatch.envs.docs
 mkdocs-material-extensions==1.3.1
     # via mkdocs-material
@@ -142,11 +148,11 @@ mkdocstrings==0.25.2
     # via
     #   hatch.envs.docs
     #   mkdocstrings-python
-mkdocstrings-python==1.9.0
+mkdocstrings-python==1.10.9
     # via hatch.envs.docs
 mypy-extensions==1.0.0
     # via black
-packaging==24.0
+packaging==24.1
     # via
     #   black
     #   mkdocs
@@ -156,18 +162,18 @@ pathspec==0.12.1
     # via
     #   black
     #   mkdocs
-pillow==10.3.0
+pillow==10.4.0
     # via
     #   cairosvg
     #   mkdocs-material
-platformdirs==4.2.0
+platformdirs==4.2.2
     # via
     #   black
-    #   mkdocs
+    #   mkdocs-get-deps
     #   mkdocstrings
 pycparser==2.22
     # via cffi
-pygments==2.17.2
+pygments==2.18.0
     # via mkdocs-material
 pymdown-extensions==10.9
     # via
@@ -181,14 +187,17 @@ python-dateutil==2.9.0.post0
     # via ghp-import
 pytz==2024.1
     # via mkdocs-git-revision-date-localized-plugin
-pyyaml==6.0.1
+pyyaml==6.0.2
     # via
     #   mike
     #   mkdocs
+    #   mkdocs-get-deps
     #   pymdown-extensions
     #   pyyaml-env-tag
 pyyaml-env-tag==0.1
-    # via mkdocs
+    # via
+    #   mike
+    #   mkdocs
 regex==2024.7.24
     # via mkdocs-material
 requests==2.32.3
@@ -197,23 +206,25 @@ six==1.16.0
     # via python-dateutil
 smmap==5.0.1
     # via gitdb
-sqlparse==0.5.0
+sqlparse==0.5.1
     # via django
-tinycss2==1.2.1
+tinycss2==1.3.0
     # via
     #   cairosvg
     #   cssselect2
+tzdata==2024.1
+    # via django
 urllib3==2.2.2
     # via requests
 verspec==0.1.0
     # via mike
 watchdog==5.0.0
     # via mkdocs
-wcmatch==8.5.1
+wcmatch==9.0
     # via mkdocs-include-markdown-plugin
 webencodings==0.5.1
     # via
     #   cssselect2
     #   tinycss2
-zipp==3.19.1
+zipp==3.20.1
     # via importlib-metadata