Skip to content

Commit

Permalink
refactor: enhance pdm and Read the Docs integration (#505)
Browse files Browse the repository at this point in the history
  • Loading branch information
huxuan authored Apr 28, 2024
1 parent 9df9b1d commit 931acaf
Show file tree
Hide file tree
Showing 12 changed files with 98 additions and 76 deletions.
2 changes: 0 additions & 2 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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 }}
Expand Down
2 changes: 1 addition & 1 deletion .gitlab/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
19 changes: 11 additions & 8 deletions .readthedocs.yaml
Original file line number Diff line number Diff line change
@@ -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.
Expand All @@ -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
17 changes: 15 additions & 2 deletions .renovaterc.json
Original file line number Diff line number Diff line change
Expand Up @@ -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]"
]
},
{
Expand Down Expand Up @@ -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": [
Expand Down
45 changes: 21 additions & 24 deletions Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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

########################################################################################
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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

Expand All @@ -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
Expand Down
2 changes: 1 addition & 1 deletion pyproject.toml
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
[build-system]
build-backend = "pdm.backend"
requires = [
"pdm-backend",
"pdm-backend==2.2.1",
]

[project]
Expand Down
19 changes: 11 additions & 8 deletions template/.readthedocs.yaml → template/.readthedocs.yaml.jinja
Original file line number Diff line number Diff line change
@@ -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.
Expand All @@ -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
17 changes: 15 additions & 2 deletions template/.renovaterc.json.jinja
Original file line number Diff line number Diff line change
Expand Up @@ -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]"
]
},
{
Expand Down Expand Up @@ -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",
Expand Down
45 changes: 21 additions & 24 deletions template/Makefile.jinja
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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

########################################################################################
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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

Expand All @@ -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
Expand Down
Loading

0 comments on commit 931acaf

Please sign in to comment.