chore: Download existing changelog if exists for incremental generati…

…on. (#151)

.github/workflows/ci.yml

@@ -3,17 +3,16 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
       - name: Set up Python ${{ matrix.python-version }}
         uses: actions/setup-python@v4
         with:
           cache: pip
           python-version: ${{ matrix.python-version }}
       - run: env | sort
       - run: make dev
-      - run: make lint
-      - run: make test
-      - run: make docs
-      - run: make build
+      - run: make lint test docs build
     strategy:
       matrix:
         python-version:

.github/workflows/pages.yml

@@ -12,7 +12,7 @@ jobs:
           python-version: '3.11'
       - run: env | sort
       - run: make dev-docs
-      - run: make docs-all
+      - run: make docs
       - name: Upload pages artifact
         uses: actions/upload-pages-artifact@v2
         with:

.gitlab-ci.yml

@@ -32,10 +32,7 @@ ci:
   script:
     - env | sort
     - make dev
-    - make lint
-    - make test
-    - make docs
-    - make build
+    - make lint test docs build
   stage: lint_test
 package:
   only:
@@ -63,7 +60,7 @@ pages:
   script:
     - env | sort
     - make dev-docs
-    - make docs-all
+    - make docs
   stage: build_release
 release:
   release:

.readthedocs.yaml

@@ -1,7 +1,8 @@
 build:
   jobs:
     post_build:
-      - make reports
+      - make docs-mypy
+      - make docs-coverage
     post_checkout:
       - git fetch --unshallow || true
     post_install:

Makefile

@@ -1,4 +1,4 @@
-.PHONY: clean deepclean install dev black isort mypy ruff toml-sort lint pre-commit test freeze version build upload docs docs-autobuild docs-mypy docs-coverage reports changelog docs-all
+.PHONY: clean deepclean install dev black isort mypy ruff toml-sort lint pre-commit test-run test freeze version build upload docs-autobuild changelog docs-gen docs-mypy docs-coverage docs
 
 ########################################################################################
 # Variables
@@ -10,6 +10,10 @@ PIPRUN := $(if $(and $(shell [ "$$CI" != "true" ] && echo 1),$(shell command -v
 # Documentation target directory, will be adapted to specific folder for readthedocs.
 PUBLIC_DIR := $(if $(shell [ "$$READTHEDOCS" = "True" ] && echo 1),$$READTHEDOCS_OUTPUT/html,public)
 
+# URL and Path of changelog source code.
+CHANGELOG_URL := https://serious-scaffold.github.io/serious-scaffold-python/_sources/changelog.md.txt
+CHANGELOG_PATH := docs/changelog.md
+
 ########################################################################################
 # Development Environment Management
 ########################################################################################
@@ -86,67 +90,70 @@ pre-commit:
 # Test
 ########################################################################################
 
-# Run test with coverage report.
-test:
+# Clean and run test with coverage.
+test-run:
 	${PIPRUN} python -m coverage erase
 	${PIPRUN} python -m coverage run -m pytest
+
+# Generate coverage report for terminal and xml.
+test: test-run
 	${PIPRUN} python -m coverage report
 	${PIPRUN} python -m coverage xml
 
 ########################################################################################
 # Package
 ########################################################################################
 
-# Show currently installed dependecies excluding the package itself with versions
+# Show currently installed dependecies excluding the package itself with versions.
 freeze:
 	@${PIPRUN} pip freeze --exclude-editable
 
 # Get the version of the package.
 version:
 	${PIPRUN} python -m setuptools_scm
 
-# Build the package
+# Build the package.
 build:
 	${PIPRUN} python -m build
 
-# Upload the package
+# Upload the package.
 upload:
 	${PIPRUN} python -m twine upload dist/*
 
 ########################################################################################
 # Documentation
 ########################################################################################
 
-# Generate documentation.
-docs:
-	${PIPRUN} python -m sphinx.cmd.build docs ${PUBLIC_DIR}
-
 # Generate documentation with auto build when changes happen.
 docs-autobuild:
 	${PIPRUN} python -m sphinx_autobuild docs ${PUBLIC_DIR} \
 		--watch README.md \
 		--watch src
 
+# Generate changelog from git commits.
+# NOTE(xuan.hu): Need to be run before document generation to take effect.
+changelog:
+	@if wget -q --spider ${CHANGELOG_URL}; then \
+		echo "Existing Changelog found at '${CHANGELOG_URL}', download for incremental generation."; \
+		wget -q -O ${CHANGELOG_PATH} ${CHANGELOG_URL}; \
+	fi
+	${PIPRUN} git-changelog -ETrio docs/changelog.md -c conventional -s build,chore,ci,docs,feat,fix,perf,refactor,revert,style,test
+
+# Build documentation only from src.
+docs-gen:
+	${PIPRUN} python -m sphinx.cmd.build docs ${PUBLIC_DIR}
+
 # Generate mypy reports.
-docs-mypy: docs
+docs-mypy: docs-gen
 	${PIPRUN} python -m mypy src test --html-report ${PUBLIC_DIR}/reports/mypy
 
-# Generate coverage reports and badge.
-docs-coverage: docs
-	${PIPRUN} python -m coverage erase
-	${PIPRUN} python -m coverage run -m pytest
+# Generate html coverage reports with badge.
+docs-coverage: test-run docs-gen
 	${PIPRUN} python -m coverage html -d ${PUBLIC_DIR}/reports/coverage
 	${PIPRUN} bash scripts/generate-coverage-badge.sh ${PUBLIC_DIR}/reports/coverage
 
-# Generate all reports.
-reports: docs-mypy docs-coverage
-
-# Generate changelog from git commits.
-changelog:
-	${PIPRUN} git-changelog -ETrio docs/changelog.md -c conventional -s build,chore,ci,docs,feat,fix,perf,refactor,revert,style,test
-
 # Generate all documentation with reports.
-docs-all: changelog docs reports
+docs: changelog docs-gen docs-mypy docs-coverage
 
 ########################################################################################
 # End

template/.readthedocs.yaml.jinja

@@ -1,7 +1,8 @@
 build:
   jobs:
     post_build:
-      - make reports
+      - make docs-mypy
+      - make docs-coverage
     post_checkout:
       - git fetch --unshallow || true
     post_install:

template/Makefile.jinja

@@ -1,4 +1,5 @@
-.PHONY: clean deepclean install dev black isort mypy ruff toml-sort lint pre-commit test freeze version build upload docs docs-autobuild docs-mypy docs-coverage reports changelog docs-all
+[% from pathjoin("includes", "variable.jinja") import page_url with context -%]
+.PHONY: clean deepclean install dev black isort mypy ruff toml-sort lint pre-commit test-run test freeze version build upload docs-autobuild changelog docs-gen docs-mypy docs-coverage docs
 
 ########################################################################################
 # Variables
@@ -10,6 +11,10 @@ PIPRUN := $(if $(and $(shell [ "$$CI" != "true" ] && echo 1),$(shell command -v
 # Documentation target directory, will be adapted to specific folder for readthedocs.
 PUBLIC_DIR := $(if $(shell [ "$$READTHEDOCS" = "True" ] && echo 1),$$READTHEDOCS_OUTPUT/html,public)
 
+# URL and Path of changelog source code.
+CHANGELOG_URL := https://{{ page_url() }}/_sources/changelog.md.txt
+CHANGELOG_PATH := docs/changelog.md
+
 ########################################################################################
 # Development Environment Management
 ########################################################################################
@@ -88,67 +93,70 @@ pre-commit:
 # Test
 ########################################################################################
 
-# Run test with coverage report.
-test:
+# Clean and run test with coverage.
+test-run:
 	${PIPRUN} python -m coverage erase
 	${PIPRUN} python -m coverage run -m pytest
+
+# Generate coverage report for terminal and xml.
+test: test-run
 	${PIPRUN} python -m coverage report
 	${PIPRUN} python -m coverage xml
 
 ########################################################################################
 # Package
 ########################################################################################
 
-# Show currently installed dependecies excluding the package itself with versions
+# Show currently installed dependecies excluding the package itself with versions.
 freeze:
 	@${PIPRUN} pip freeze --exclude-editable
 
 # Get the version of the package.
 version:
 	${PIPRUN} python -m setuptools_scm
 
-# Build the package
+# Build the package.
 build:
 	${PIPRUN} python -m build
 
-# Upload the package
+# Upload the package.
 upload:
 	${PIPRUN} python -m twine upload dist/*
 
 ########################################################################################
 # Documentation
 ########################################################################################
 
-# Generate documentation.
-docs:
-	${PIPRUN} python -m sphinx.cmd.build docs ${PUBLIC_DIR}
-
 # Generate documentation with auto build when changes happen.
 docs-autobuild:
 	${PIPRUN} python -m sphinx_autobuild docs ${PUBLIC_DIR} \
 		--watch README.md \
 		--watch src
 
+# Generate changelog from git commits.
+# NOTE(xuan.hu): Need to be run before document generation to take effect.
+changelog:
+	@if wget -q --spider ${CHANGELOG_URL}; then \
+		echo "Existing Changelog found at '${CHANGELOG_URL}', download for incremental generation."; \
+		wget -q -O ${CHANGELOG_PATH} ${CHANGELOG_URL}; \
+	fi
+	${PIPRUN} git-changelog -ETrio docs/changelog.md -c conventional -s build,chore,ci,docs,feat,fix,perf,refactor,revert,style,test
+
+# Build documentation only from src.
+docs-gen:
+	${PIPRUN} python -m sphinx.cmd.build docs ${PUBLIC_DIR}
+
 # Generate mypy reports.
-docs-mypy: docs
+docs-mypy: docs-gen
 	${PIPRUN} python -m mypy src test --html-report ${PUBLIC_DIR}/reports/mypy
 
-# Generate coverage reports and badge.
-docs-coverage: docs
-	${PIPRUN} python -m coverage erase
-	${PIPRUN} python -m coverage run -m pytest
+# Generate html coverage reports with badge.
+docs-coverage: test-run docs-gen
 	${PIPRUN} python -m coverage html -d ${PUBLIC_DIR}/reports/coverage
 	${PIPRUN} bash scripts/generate-coverage-badge.sh ${PUBLIC_DIR}/reports/coverage
 
-# Generate all reports.
-reports: docs-mypy docs-coverage
-
-# Generate changelog from git commits.
-changelog:
-	${PIPRUN} git-changelog -ETrio docs/changelog.md -c conventional -s build,chore,ci,docs,feat,fix,perf,refactor,revert,style,test
-
 # Generate all documentation with reports.
-docs-all: changelog docs reports
+docs: changelog docs-gen docs-mypy docs-coverage
 
 ########################################################################################
 # End

template/[% if repo_host_type == 'github.com' %].github[% endif %]/workflows/ci.yml.jinja

@@ -4,17 +4,16 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
       - name: Set up Python {{ '${{ matrix.python-version }}' }}
         uses: actions/setup-python@v4
         with:
           cache: pip
           python-version: {{ '${{ matrix.python-version }}' }}
       - run: env | sort
       - run: make dev
-      - run: make lint
-      - run: make test
-      - run: make docs
-      - run: make build
+      - run: make lint test docs build
     strategy:
       matrix:
         python-version:

template/[% if repo_host_type == 'github.com' %].github[% endif %]/workflows/pages.yml.jinja

@@ -12,7 +12,7 @@ jobs:
           python-version: '{{ default_py }}'
       - run: env | sort
       - run: make dev-docs
-      - run: make docs-all
+      - run: make docs
       - name: Upload pages artifact
         uses: actions/upload-pages-artifact@v2
         with:

template/[% if repo_host_type == 'gitlab.com' or repo_host_type == 'gitlab-self-managed' %].gitlab-ci.yml[% endif %].jinja

@@ -41,10 +41,7 @@ ci:
   script:
     - env | sort
     - make dev
-    - make lint
-    - make test
-    - make docs
-    - make build
+    - make lint test docs build
   stage: lint_test
 package:
   only:
@@ -72,7 +69,7 @@ pages:
   script:
     - env | sort
     - make dev-docs
-    - make docs-all
+    - make docs
   stage: build_release
 release:
   release: