Cleaned up makefile, added 'make help', newer release.mk

2 files changed, 68 insertions, 30 deletions

diff --git a/Makefile b/Makefile
index 31a0081..01ff3a6 100644
--- a/Makefile
+++ b/Makefile
@@ -2,7 +2,7 @@
 # Options
 #
 
-PYTHON = python
+PYTHON = python3
 FILE_WITH_VERSION = src/gtimelog/__init__.py
 FILE_WITH_CHANGELOG = CHANGES.rst
 
@@ -24,40 +24,43 @@ schema_files = $(schema_dir)/gschemas.compiled
 runtime_files = $(schema_files) $(mo_files)
 
 .PHONY: all
-all: $(manpages) $(runtime_files)
+all: $(manpages) $(runtime_files)       ##: build everything
 
 .PHONY: run
-run: $(runtime_files)
+run: $(runtime_files)                   ##: run directly from the source tree
 	./gtimelog
 
+.PHONY: test
+test:                                   ##: run tests
+	tox -p auto
+
 .PHONY: check
-check: test
+check: test                             ##: run tests and additional checks
+# 'make check' is defined in release.mk and here's how you can override it
+define check_recipe =
 	desktop-file-validate gtimelog.desktop
 	appstream-util validate-relax gtimelog.appdata.xml
-
-.PHONY: test
-test:
-	tox -p auto
+endef
 
 .PHONY: coverage
-coverage:
+coverage:                               ##: measure test coverage
 	tox -e coverage
 
 .PHONY: coverage-diff
-coverage-diff: coverage
+coverage-diff: coverage                 ##: find untested code in this branch
 	$(COVERAGE) xml
 	diff-cover coverage.xml
 
 .PHONY: flake8
-flake8:
+flake8:                                 ##: check for style problems
 	tox -e flake8
 
 .PHONY: isort
-isort:
+isort:                                  ##: check for badly sorted improts
 	tox -e isort
 
 .PHONY: update-translations
-update-translations:
+update-translations:                    ##: extract new translatable strings from source code and ui files
 	git config filter.po.clean 'msgcat - --no-location'
 	cd $(po_dir) && intltool-update -g gtimelog -p
 	for po in $(po_files); do msgmerge -U $$po $(po_dir)/gtimelog.pot; done
@@ -66,17 +69,19 @@ update-translations:
 mo-files: $(mo_files)
 
 .PHONY: flatpak
-flatpak:
+flatpak:                                ##: build a flatpak package
 	# you may need to install the platform and sdk before this will work
-	# flatpak install flathub org.gnome.Platform//3.32 org.gnome.Sdk//3.32
+	# flatpak install flathub org.gnome.Platform//3.82 org.gnome.Sdk//3.38
+	# note that this builds the code from git master, not your local working tree!
 	flatpak-builder --force-clean build/flatpak flatpak/org.gtimelog.GTimeLog.yaml
 	# to run it do
 	# flatpak-builder --run build/flatpak flatpak/org.gtimelog.GTimeLog.yaml gtimelog
 
 .PHONY: flatpak-install
-flatpak-install:
+flatpak-install:                        ##: build and install a flatpak package
 	# you may need to install the platform and sdk before this will work
-	# flatpak install flathub org.gnome.Platform//3.30 org.gnome.Sdk//3.30
+	# flatpak install flathub org.gnome.Platform//3.38 org.gnome.Sdk//3.38
+	# note that this builds the code from git master, not your local working tree!
 	flatpak-builder --force-clean build/flatpak flatpak/org.gtimelog.GTimeLog.yaml --install --user
 	# to run it do
 	# flatpak run org.gtimelog.GTimeLog
@@ -89,7 +94,7 @@ $(schema_files): $(schema_dir)/org.gtimelog.gschema.xml
 	glib-compile-schemas $(schema_dir)
 
 .PHONY: clean
-clean:
+clean:                                  ##: clean build artifacts
 	rm -rf temp tmp build gtimelog.egg-info $(runtime_files) $(mo_dir)
 	find -name '*.pyc' -delete
 
diff --git a/release.mk b/release.mk
index 01e8690..539dff0 100644
--- a/release.mk
+++ b/release.mk
@@ -1,4 +1,4 @@
-# release.mk version 1.4 (2019-04-23)
+# release.mk version 2.0 (2020-10-11)
 #
 # Helpful Makefile rules for releasing Python packages.
 # https://github.com/mgedmin/python-project-skel
@@ -11,10 +11,10 @@ CHANGELOG_FORMAT ?= $(changelog_ver) ($(changelog_date))
 DISTCHECK_DIFF_OPTS ?= $(DISTCHECK_DIFF_DEFAULT_OPTS)
 
 # These should be fine
-PYTHON ?= python
+PYTHON ?= python3
 PYPI_PUBLISH ?= rm -rf dist && $(PYTHON) setup.py -q sdist bdist_wheel && twine check dist/* && twine upload dist/*
 LATEST_RELEASE_MK_URL = https://raw.githubusercontent.com/mgedmin/python-project-skel/master/release.mk
-DISTCHECK_DIFF_DEFAULT_OPTS = -x PKG-INFO -x setup.cfg -x '*.egg-info' -I'^\#'
+DISTCHECK_DIFF_DEFAULT_OPTS = -x PKG-INFO -x setup.cfg -x '*.egg-info' -x .github -I'^\#'
 
 # These should be fine, as long as you use Git
 VCS_GET_LATEST ?= git pull
@@ -27,30 +27,58 @@ VCS_COMMIT_AND_PUSH ?= git commit -av -m "Post-release version bump" && git push
 changelog_ver = `$(PYTHON) setup.py --version`
 changelog_date = `LC_ALL=C date +'$(CHANGELOG_DATE_FORMAT)'`
 
+# Tweaking the look of 'make help'; most of these are awk literals and need the quotes
+HELP_INDENT = ""
+HELP_PREFIX = "make "
+HELP_WIDTH = 24
+HELP_SEPARATOR = " \# "
+HELP_SECTION_SEP = "\n"
+
+.PHONY: help
+help:
+	@grep -Eh -e '^[a-zA-Z0-9_ -]+:.*?##: .*$$' -e '^##:' $(MAKEFILE_LIST) \
+	    | awk 'BEGIN {FS = "(^|:[^#]*)##: "; section=""}; \
+	          /^##:/ {printf "%s%s\n%s", section, $$2, $(HELP_SECTION_SEP); section=$(HELP_SECTION_SEP)} \
+	          /^[^#]/ {printf "%s\033[36m%-$(HELP_WIDTH)s\033[0m%s%s\n", \
+	                   $(HELP_INDENT), $(HELP_PREFIX) $$1, $(HELP_SEPARATOR), $$2}'
 
 .PHONY: dist
 dist:
 	$(PYTHON) setup.py -q sdist bdist_wheel
 
+# Provide a default 'make check' to be the same as 'make test', since that's
+# what 80% of my projects use, but make it possible to override.  Now
+# overriding Make rules is painful, so instead of a regular rule definition
+# you'll have to override the check_recipe macro.
+.PHONY: check
+check:
+	$(check_recipe)
+
+ifndef check_recipe
+define check_recipe =
+	@$(MAKE) test
+endef
+endif
+
 .PHONY: distcheck
 distcheck: distcheck-vcs distcheck-sdist
 
 .PHONY: distcheck-vcs
 distcheck-vcs:
+ifndef FORCE
 	# Bit of a chicken-and-egg here, but if the tree is unclean, make
 	# distcheck-sdist will fail.
-ifndef FORCE
 	@test -z "`$(VCS_STATUS) 2>&1`" || { echo; echo "Your working tree is not clean:" 1>&2; $(VCS_STATUS) 1>&2; exit 1; }
 endif
 
-# NB: do not use $(MAKE) because then make -n distcheck will actually run
-# it instead of just printing what it does
+# NB: do not use $(MAKE) in rules with multiple shell commands joined by &&
+# because then make -n distcheck will actually run those instead of just
+# printing what it does
 
 # TBH this could (and probably should) be replaced by check-manifest
 
 .PHONY: distcheck-sdist
-distcheck-sdist:
-	make dist
+distcheck-sdist: dist
 	pkg_and_version=`$(PYTHON) setup.py --name`-`$(PYTHON) setup.py --version` && \
 	  rm -rf tmp && \
 	  mkdir tmp && \
@@ -97,20 +125,24 @@ check-changelog:
 	    grep -q "^$$ver_and_date$$" $(FILE_WITH_CHANGELOG) || { \
 	        echo "$(FILE_WITH_CHANGELOG) has no entry for $$ver_and_date"; exit 1; }
 
-# NB: do not use $(MAKE) because then make -n releasechecklist will
-# actually run the distcheck instead of just printing what it does
+
+# NB: the Makefile that includes release.mk may want to add additional
+# dependencies to the releasechecklist target, but I want 'make distcheck' to
+# happen last, so that's why I put it into the recipe and not at the end of the
+# list of dependencies.
 
 .PHONY: releasechecklist
 releasechecklist: check-latest-rules check-latest-version check-version-number check-long-description check-changelog
-	make distcheck
+	$(MAKE) distcheck
 
 .PHONY: release
-release: releasechecklist do-release
+release: releasechecklist do-release    ##: prepare a new PyPI release
 
 .PHONY: do-release
 do-release:
 	$(release_recipe)
 
+ifndef release_recipe
 define release_recipe =
 	# I'm chicken so I won't actually do these things yet
 	@echo "Please run"
@@ -124,3 +156,4 @@ define release_recipe =
 	@echo '  $(VCS_COMMIT_AND_PUSH)'
 	@echo
 endef
+endif