refactor: enhance pdm and Read the Docs integration

.github/workflows/release.yml

@@ -16,8 +16,6 @@ jobs:
         uses: actions/configure-pages@983d7736d9b0ae728b81ab479565c72886d7745b # v5.0.0
       - run: env | sort
       - run: make dev-doc
-        env:
-          PDM_NO_EDITABLE: true
       - run: make doc
         env:
           CI_PAGES_URL: ${{ steps.pages.outputs.base_url }}

.gitlab/workflows/release.yml

@@ -7,7 +7,7 @@ pages-build:
   rules:
     - if: $CI_COMMIT_TAG =~ /^v?(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(-?(a|b|rc)(0|[1-9][0-9]*)?)?$/
   script:
-    - PDM_NO_EDITABLE=true make dev-doc
+    - make dev-doc
     - make doc
     - make release-notes > release-notes.md
   stage: release

.readthedocs.yaml

@@ -1,10 +1,6 @@
 build:
   jobs:
-    post_build:
-      - make doc-mypy
-      - make doc-coverage
     post_checkout:
-      - env | sort
       - git fetch --unshallow || true
       # Cancel building pull requests when there aren't changed in the related files and folders.
       # If there are no changes (git diff exits with 0) we force the command to return with 183.
@@ -21,14 +17,21 @@ build:
         then
           exit 183;
         fi
+    post_system_dependencies:
+      - env | sort
+    pre_create_environment:
+      - asdf plugin add pdm
+      - asdf install pdm 2.15.0
+      - asdf global pdm 2.15.0
     post_install:
-      - python -m pip install --upgrade --no-cache-dir pdm==2.15.0
-      - PDM_NO_EDITABLE=true make dev-doc
+      - VIRTUAL_ENV=$READTHEDOCS_VIRTUALENV_PATH make dev-doc
     pre_build:
-      - CI_PAGES_URL=https://${READTHEDOCS_PROJECT}.readthedocs.io/${READTHEDOCS_LANGUAGE}/stable make changelog
+      - VIRTUAL_ENV=$READTHEDOCS_VIRTUALENV_PATH CI_PAGES_URL=https://${READTHEDOCS_PROJECT}.readthedocs.io/${READTHEDOCS_LANGUAGE}/stable make changelog
+    post_build:
+      - VIRTUAL_ENV=$READTHEDOCS_VIRTUALENV_PATH make doc-mypy doc-coverage
   os: ubuntu-22.04
   tools:
-    python: '3'
+    python: "3.12"
 sphinx:
   fail_on_warning: true
 version: 2

.renovaterc.json

@@ -21,8 +21,10 @@
                 "^template/docs/.+\\.md(\\.jinja)?$"
             ],
             "matchStrings": [
-                "pipx install (?<depName>.*?)==(?<currentValue>.*?)[;\n]",
-                "pip install.* (?<depName>.*?)==(?<currentValue>.*?)[\"\n]"
+                "asdf global (?<depName>.*?) (?<currentValue>.*?)\n",
+                "asdf install (?<depName>.*?) (?<currentValue>.*?)\n",
+                "pip install.* (?<depName>.*?)==(?<currentValue>.*?)[\"\n]",
+                "pipx install (?<depName>.*?)==(?<currentValue>.*?)[;\n]"
             ]
         },
         {
@@ -132,6 +134,17 @@
                 ]
             }
         },
+        {
+            "matchDatasources": [
+                "pypi"
+            ],
+            "postUpgradeTasks": {
+                "commands": [
+                    "find template -type f -exec sed -i 's|{{{depName}}} {{{currentValue}}}|{{{depName}}} {{{newValue}}}|g' {} +",
+                    "find template -type f -exec sed -i 's|{{{depName}}}=={{{currentValue}}}|{{{depName}}}=={{{newValue}}}|g' {} +"
+                ]
+            }
+        },
         {
             "commitMessageTopic": "serious-scaffold-python",
             "matchDepTypes": [

Makefile

@@ -4,11 +4,8 @@
 # Variables
 ########################################################################################
 
-# Global option for pdm, when in CI or readthedocs environment, no need to use venv.
-PDM_GLOBAL := $(shell [ "$$CI" = "true" ] || [ "$$READTHEDOCS" = "True" ] && echo "--global --project .")
-
 # Documentation target directory, will be adapted to specific folder for readthedocs.
-PUBLIC_DIR := $(shell [ "$$READTHEDOCS" = "True" ] && echo "$$READTHEDOCS_OUTPUT/html" || echo "public")
+PUBLIC_DIR := $(shell [ "$$READTHEDOCS" = "True" ] && echo "$${READTHEDOCS_OUTPUT}html" || echo "public")
 
 # URL and Path of changelog source code.
 CHANGELOG_URL := $(shell echo $${CI_PAGES_URL:-https://serious-scaffold.github.io/ss-python}/_sources/changelog.md.txt)
@@ -47,16 +44,16 @@ deepclean: clean
 
 # Install the package in editable mode.
 install:
-	pdm install $(PDM_GLOBAL) --prod
+	pdm install --prod
 
 # Install the package in editable mode with specific optional dependencies.
 dev-%:
-	pdm install $(PDM_GLOBAL) --dev --group $*
+	pdm install --dev --group $*
 
 # Prepare the development environment.
 # Install the pacakge in editable mode with all optional dependencies and pre-commit hoook.
 dev:
-	pdm install $(PDM_GLOBAL)
+	pdm install
 	if [ "$(CI)" != "true" ] && command -v pre-commit > /dev/null 2>&1; then pre-commit install; fi
 
 ########################################################################################
@@ -65,19 +62,19 @@ dev:
 
 # Check lint with mypy.
 mypy:
-	pdm run $(PDM_GLOBAL) python -m mypy .
+	pdm run python -m mypy .
 
 # Lint with ruff.
 ruff:
-	pdm run $(PDM_GLOBAL) python -m ruff check .
+	pdm run python -m ruff check .
 
 # Format with ruff.
 ruff-format:
-	pdm run $(PDM_GLOBAL) python -m ruff format --check .
+	pdm run python -m ruff format --check .
 
 # Check lint with toml-sort.
 toml-sort:
-	pdm run $(PDM_GLOBAL) toml-sort --check pyproject.toml
+	pdm run toml-sort --check pyproject.toml
 
 # Check lint with all linters.
 lint: mypy ruff ruff-format toml-sort
@@ -92,13 +89,13 @@ pre-commit:
 
 # Clean and run test with coverage.
 test-run:
-	pdm run $(PDM_GLOBAL) python -m coverage erase
-	pdm run $(PDM_GLOBAL) python -m coverage run -m pytest
+	pdm run python -m coverage erase
+	pdm run python -m coverage run -m pytest
 
 # Generate coverage report for terminal and xml.
 test: test-run
-	pdm run $(PDM_GLOBAL) python -m coverage report
-	pdm run $(PDM_GLOBAL) python -m coverage xml
+	pdm run python -m coverage report
+	pdm run python -m coverage xml
 
 ########################################################################################
 # Package
@@ -118,7 +115,7 @@ publish:
 
 # Generate documentation with auto build when changes happen.
 doc-autobuild:
-	pdm run $(PDM_GLOBAL) python -m sphinx_autobuild docs $(PUBLIC_DIR) \
+	pdm run python -m sphinx_autobuild docs $(PUBLIC_DIR) \
 		--watch README.md \
 		--watch src
 
@@ -129,24 +126,24 @@ changelog:
 		echo "Existing Changelog found at '$(CHANGELOG_URL)', download for incremental generation."; \
 		wget -q -O $(CHANGELOG_PATH) $(CHANGELOG_URL); \
 	fi
-	pdm run $(PDM_GLOBAL) git-changelog -ETrio $(CHANGELOG_PATH) -c conventional -s build,chore,ci,doc,feat,fix,perf,refactor,revert,style,test
+	pdm run git-changelog -ETrio $(CHANGELOG_PATH) -c conventional -s build,chore,ci,doc,feat,fix,perf,refactor,revert,style,test
 
 # Generate release notes from changelog.
 release-notes:
-	@pdm run $(PDM_GLOBAL) git-changelog --input $(CHANGELOG_PATH) --release-notes
+	@pdm run git-changelog --input $(CHANGELOG_PATH) --release-notes
 
 # Build documentation only from src.
 doc-gen:
-	pdm run $(PDM_GLOBAL) python -m sphinx.cmd.build docs $(PUBLIC_DIR)
+	pdm run python -m sphinx.cmd.build docs $(PUBLIC_DIR)
 
 # Generate mypy reports.
-doc-mypy: doc-gen
-	pdm run $(PDM_GLOBAL) python -m mypy src tests --html-report $(PUBLIC_DIR)/reports/mypy
+doc-mypy:
+	pdm run python -m mypy src tests --html-report $(PUBLIC_DIR)/reports/mypy
 
 # Generate html coverage reports with badge.
-doc-coverage: test-run doc-gen
-	pdm run $(PDM_GLOBAL) python -m coverage html -d $(PUBLIC_DIR)/reports/coverage
-	pdm run $(PDM_GLOBAL) bash scripts/generate-coverage-badge.sh $(PUBLIC_DIR)/_static/badges
+doc-coverage: test-run
+	pdm run python -m coverage html -d $(PUBLIC_DIR)/reports/coverage
+	pdm run bash scripts/generate-coverage-badge.sh $(PUBLIC_DIR)/_static/badges
 
 # Generate all documentation with reports.
 doc: changelog doc-gen doc-mypy doc-coverage

pyproject.toml

@@ -1,7 +1,7 @@
 [build-system]
 build-backend = "pdm.backend"
 requires = [
-  "pdm-backend",
+  "pdm-backend==2.2.1",
 ]
 
 [project]

template/.readthedocs.yaml → template/.readthedocs.yaml.jinja

@@ -1,10 +1,6 @@
 build:
   jobs:
-    post_build:
-      - make doc-mypy
-      - make doc-coverage
     post_checkout:
-      - env | sort
       - git fetch --unshallow || true
       # Cancel building pull requests when there aren't changed in the related files and folders.
       # If there are no changes (git diff exits with 0) we force the command to return with 183.
@@ -21,14 +17,21 @@ build:
         then
           exit 183;
         fi
+    post_system_dependencies:
+      - env | sort
+    pre_create_environment:
+      - asdf plugin add pdm
+      - asdf install pdm 2.15.0
+      - asdf global pdm 2.15.0
     post_install:
-      - python -m pip install --upgrade --no-cache-dir pdm==2.15.0
-      - PDM_NO_EDITABLE=true make dev-doc
+      - VIRTUAL_ENV=$READTHEDOCS_VIRTUALENV_PATH make dev-doc
     pre_build:
-      - CI_PAGES_URL=https://${READTHEDOCS_PROJECT}.readthedocs.io/${READTHEDOCS_LANGUAGE}/stable make changelog
+      - VIRTUAL_ENV=$READTHEDOCS_VIRTUALENV_PATH CI_PAGES_URL=https://${READTHEDOCS_PROJECT}.readthedocs.io/${READTHEDOCS_LANGUAGE}/stable make changelog
+    post_build:
+      - VIRTUAL_ENV=$READTHEDOCS_VIRTUALENV_PATH make doc-mypy doc-coverage
   os: ubuntu-22.04
   tools:
-    python: '3'
+    python: "{{ default_py }}"
 sphinx:
   fail_on_warning: true
 version: 2

template/.renovaterc.json.jinja

@@ -24,8 +24,10 @@
 [%- endif %]
             ],
             "matchStrings": [
-                "pipx install (?<depName>.*?)==(?<currentValue>.*?)[;\n]",
-                "pip install.* (?<depName>.*?)==(?<currentValue>.*?)[\"\n]"
+                "asdf global (?<depName>.*?) (?<currentValue>.*?)\n",
+                "asdf install (?<depName>.*?) (?<currentValue>.*?)\n",
+                "pip install.* (?<depName>.*?)==(?<currentValue>.*?)[\"\n]",
+                "pipx install (?<depName>.*?)==(?<currentValue>.*?)[;\n]"
             ]
         },
         {
@@ -142,6 +144,17 @@
                 ]
             }
         },
+        {
+            "matchDatasources": [
+                "pypi"
+            ],
+            "postUpgradeTasks": {
+                "commands": [
+                    "find template -type f -exec sed -i {{ '\'s|{{{depName}}} {{{currentValue}}}|{{{depName}}} {{{newValue}}}|g\' {} +' }}",
+                    "find template -type f -exec sed -i {{ '\'s|{{{depName}}}=={{{currentValue}}}|{{{depName}}}=={{{newValue}}}|g\' {} +' }}"
+                ]
+            }
+        },
 [%- endif %]
         {
             "commitMessageTopic": "serious-scaffold-python",

template/Makefile.jinja

@@ -6,11 +6,8 @@
 # Variables
 ########################################################################################
 
-# Global option for pdm, when in CI or readthedocs environment, no need to use venv.
-PDM_GLOBAL := $(shell [ "$$CI" = "true" ] || [ "$$READTHEDOCS" = "True" ] && echo "--global --project .")
-
 # Documentation target directory, will be adapted to specific folder for readthedocs.
-PUBLIC_DIR := $(shell [ "$$READTHEDOCS" = "True" ] && echo "$$READTHEDOCS_OUTPUT/html" || echo "public")
+PUBLIC_DIR := $(shell [ "$$READTHEDOCS" = "True" ] && echo "$${READTHEDOCS_OUTPUT}html" || echo "public")
 
 # URL and Path of changelog source code.
 CHANGELOG_URL := $(shell echo $${CI_PAGES_URL:-https://{{ page_url() }}}/_sources/changelog.md.txt)
@@ -49,16 +46,16 @@ deepclean: clean
 
 # Install the package in editable mode.
 install:
-	pdm install $(PDM_GLOBAL) --prod
+	pdm install --prod
 
 # Install the package in editable mode with specific optional dependencies.
 dev-%:
-	pdm install $(PDM_GLOBAL) --dev --group $*
+	pdm install --dev --group $*
 
 # Prepare the development environment.
 # Install the pacakge in editable mode with all optional dependencies and pre-commit hoook.
 dev:
-	pdm install $(PDM_GLOBAL)
+	pdm install
 	if [ "$(CI)" != "true" ] && command -v pre-commit > /dev/null 2>&1; then pre-commit install; fi
 
 ########################################################################################
@@ -67,19 +64,19 @@ dev:
 
 # Check lint with mypy.
 mypy:
-	pdm run $(PDM_GLOBAL) python -m mypy .
+	pdm run python -m mypy .
 
 # Lint with ruff.
 ruff:
-	pdm run $(PDM_GLOBAL) python -m ruff check .
+	pdm run python -m ruff check .
 
 # Format with ruff.
 ruff-format:
-	pdm run $(PDM_GLOBAL) python -m ruff format --check .
+	pdm run python -m ruff format --check .
 
 # Check lint with toml-sort.
 toml-sort:
-	pdm run $(PDM_GLOBAL) toml-sort --check pyproject.toml
+	pdm run toml-sort --check pyproject.toml
 
 # Check lint with all linters.
 lint: mypy ruff ruff-format toml-sort
@@ -94,13 +91,13 @@ pre-commit:
 
 # Clean and run test with coverage.
 test-run:
-	pdm run $(PDM_GLOBAL) python -m coverage erase
-	pdm run $(PDM_GLOBAL) python -m coverage run -m pytest
+	pdm run python -m coverage erase
+	pdm run python -m coverage run -m pytest
 
 # Generate coverage report for terminal and xml.
 test: test-run
-	pdm run $(PDM_GLOBAL) python -m coverage report
-	pdm run $(PDM_GLOBAL) python -m coverage xml
+	pdm run python -m coverage report
+	pdm run python -m coverage xml
 
 ########################################################################################
 # Package
@@ -120,7 +117,7 @@ publish:
 
 # Generate documentation with auto build when changes happen.
 doc-autobuild:
-	pdm run $(PDM_GLOBAL) python -m sphinx_autobuild docs $(PUBLIC_DIR) \
+	pdm run python -m sphinx_autobuild docs $(PUBLIC_DIR) \
 		--watch README.md \
 		--watch src
 
@@ -131,24 +128,24 @@ changelog:
 		echo "Existing Changelog found at '$(CHANGELOG_URL)', download for incremental generation."; \
 		wget -q -O $(CHANGELOG_PATH) $(CHANGELOG_URL); \
 	fi
-	pdm run $(PDM_GLOBAL) git-changelog -ETrio $(CHANGELOG_PATH) -c conventional -s build,chore,ci,doc,feat,fix,perf,refactor,revert,style,test
+	pdm run git-changelog -ETrio $(CHANGELOG_PATH) -c conventional -s build,chore,ci,doc,feat,fix,perf,refactor,revert,style,test
 
 # Generate release notes from changelog.
 release-notes:
-	@pdm run $(PDM_GLOBAL) git-changelog --input $(CHANGELOG_PATH) --release-notes
+	@pdm run git-changelog --input $(CHANGELOG_PATH) --release-notes
 
 # Build documentation only from src.
 doc-gen:
-	pdm run $(PDM_GLOBAL) python -m sphinx.cmd.build docs $(PUBLIC_DIR)
+	pdm run python -m sphinx.cmd.build docs $(PUBLIC_DIR)
 
 # Generate mypy reports.
-doc-mypy: doc-gen
-	pdm run $(PDM_GLOBAL) python -m mypy src tests --html-report $(PUBLIC_DIR)/reports/mypy
+doc-mypy:
+	pdm run python -m mypy src tests --html-report $(PUBLIC_DIR)/reports/mypy
 
 # Generate html coverage reports with badge.
-doc-coverage: test-run doc-gen
-	pdm run $(PDM_GLOBAL) python -m coverage html -d $(PUBLIC_DIR)/reports/coverage
-	pdm run $(PDM_GLOBAL) bash scripts/generate-coverage-badge.sh $(PUBLIC_DIR)/_static/badges
+doc-coverage: test-run
+	pdm run python -m coverage html -d $(PUBLIC_DIR)/reports/coverage
+	pdm run bash scripts/generate-coverage-badge.sh $(PUBLIC_DIR)/_static/badges
 
 # Generate all documentation with reports.
 doc: changelog doc-gen doc-mypy doc-coverage