From efcf98e2d7ca6b84a26e64425fa272d33dbcd104 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Thu, 12 Dec 2019 22:27:54 -0600 Subject: [PATCH] Self-document Makefile --- Makefile | 157 +++++++++++++++++++++++++++++-------------------------- help.mk | 21 ++++++++ 2 files changed, 105 insertions(+), 73 deletions(-) create mode 100644 help.mk diff --git a/Makefile b/Makefile index 0ea8bcd..22fe5d4 100644 --- a/Makefile +++ b/Makefile @@ -32,78 +32,95 @@ PYTEST_STUFF = .cache src/pgwui_core/__pycache__ \ COVERAGE_STUFF = .coverage TOX_STUFF = .tox +include help.mk + all: ${TARGETS} -help: - @echo - @echo 'Usage: make TARGET' - @echo - @echo 'TARGET is one of:' - @echo 'README.html Make html version of README.rst' - @echo 'publish Update all public-facing info' - @echo ' ("check-manifest" + "upload" + "push")' - @echo 'run_tests Run regression tests' - @echo 'dist Create sdist Python package in ./dist' - @echo 'clean Removed generated data' - @echo - @echo 'Less used TARGETS are:' - @echo 'register_test Register project at pypi test site' - @echo 'register Register project at pypi live site' - @echo 'upload_test Upload project to pypi test site' - @echo 'upload Upload project to pypi live site' - @echo 'push Push repo changes to public repo' - @echo ' (Hooks at bitbucket update readthedocs)' - @echo 'check Quick run of regression tests,' - @echo 'pudb Run the python pudb debugger' - @echo ' only with the default python' - @echo 'devel/check-manifest' - @echo ' Create a check-manifest venv' - @echo 'check-manifest Run check-manifest' - @echo 'update_check-manifest' - @echo ' Upgrade check-manifest venv to latest' - @echo ' versions' - @echo - @echo 'This Makefile does not work with the docs. See:' - @echo 'cd docs; make help' +## +## Usage: make TARGET +## +## TARGET is one of: +# +## README.html Make html version of README.rst README.html: README.rst rst2html --strict README.rst > README.html +## publish Update all public-facing info +## ("check-manifest" + "upload" + "push") +.PHONY: publish +publish: check-manifest upload push + +## run_tests Run regression tests +.PHONY: run_tests +run_tests: devel/testenv + devel/testenv/bin/tox --skip-missing-interpreters + +## dist Create sdist Python package in ./dist +.PHONY: dist +dist: + rm -rf dist + ${PYTHON_EXE} setup.py sdist + + +# Expected targets + +## clean Removed generated data +.PHONY: clean +clean: + #$(MAKE) -C docs clean + rm -rf ${TARGETS} ${EXTRA_TARGETS} ${SETUPTOOLS_STUFF} \ + ${PYTEST_STUFF} ${COVERAGE_STUFF} ${TOX_STUFF} devel + +## +## Less used TARGETS are: +# # Useless targets -# Register with pypi. + +## register_test Register project at pypi test site .PHONY: register_test register_test: ${PYTHON_EXE} setup.py register -r https://testpypi.python.org/pypi +## register Register project at pypi live site .PHONY: register register: ${PYTHON_EXE} setup.py register # Not so useless targets, used by the package owners for package management + +## upload_test Upload project to pypi test site .PHONY: upload_test upload_test: ${PYTHON_EXE} setup.py sdist upload -r https://testpypi.python.org/pypi +## upload Upload project to pypi live site .PHONY: upload upload: ${PYTHON_EXE} setup.py sdist upload +## push Push repo changes to public repo +## (Hooks at bitbucket update readthedocs) .PHONY: push git push -.PHONY: publish -publish: check-manifest upload push - - -# Development related targets +## check Quick run of regression tests, +## only with the default python +.PHONY: check +check: devel/pytest + devel/pytest/bin/flake8 . + devel/pytest/bin/py.test --cov=pgwui_core tests -# Re-create development environment when setup.py changes -devel: setup.py - rm -rf devel - mkdir devel +## pudb Run the python pudb debugger +.PHONY: pudb +pudb: devel/pudb + # echo 'import pudb; pu.db' | devel/pudb/bin/python + devel/pudb/bin/python +## devel/check-manifest +## Create a check-manifest venv devel/check-manifest: devel [ -d devel/check-manifest ] \ || ( ${VIRTUALENV} devel/check-manifest ; \ @@ -111,12 +128,34 @@ devel/check-manifest: devel devel/check-manifest/bin/pip install --upgrade setuptools ; \ devel/check-manifest/bin/pip install check-manifest ) +## check-manifest Run check-manifest +check-manifest: devel/check-manifest + devel/check-manifest/bin/check-manifest + +## update_check-manifest +## Upgrade check-manifest venv to latest +## versions update_check-manifest: devel/check-manifest devel/check-manifest/bin/pip -U -check-manifest: devel/check-manifest - devel/check-manifest/bin/check-manifest +## update_testenv Upgrade the test virtual environment +update_testenv: devel/testenv + devel/testenv/bin/pip -U + +## help Show this help +## +## This Makefile does not work with the docs. See: +## cd docs; make help + + +# Development related targets + +# Re-create development environment when setup.py changes +devel: setup.py + rm -rf devel + mkdir devel +# virtualenv for development devel/testenv: devel [ -d devel/testenv ] \ || ( ${VIRTUALENV} devel/testenv ; \ @@ -124,18 +163,7 @@ devel/testenv: devel devel/testenv/bin/pip install --upgrade setuptools ; \ devel/testenv/bin/pip install tox) -update_testenv: devel/testenv - devel/testenv/bin/pip -U - -.PHONY: run_tests -run_tests: devel/testenv - devel/testenv/bin/tox --skip-missing-interpreters - -.PHONY: dist -dist: - rm -rf dist - ${PYTHON_EXE} setup.py sdist - +# virtualenv for pytest devel/pytest: devel dist if [ ! -d devel/pytest ] ; then \ ( ${VIRTUALENV} devel/pytest ; \ @@ -150,11 +178,7 @@ devel/pytest: devel dist devel/pytest/bin/pip install dist/pgwui_core-*.tar.gz ) ; \ fi -.PHONY: check -check: devel/pytest - devel/pytest/bin/flake8 . - devel/pytest/bin/py.test --cov=pgwui_core tests - +# virtualenv for pudb devel/pudb: devel dist if [ ! -d devel/pudb ] ; then \ ( ${VIRTUALENV} devel/pudb ; \ @@ -167,16 +191,3 @@ devel/pudb: devel dist ( devel/pudb/bin/pip uninstall -y pgwui_core ; \ devel/pudb/bin/pip install dist/pgwui_core-*.tar.gz ) ; \ fi - -.PHONY: pudb -pudb: devel/pudb - # echo 'import pudb; pu.db' | devel/pudb/bin/python - devel/pudb/bin/python - - -# Expected targets -.PHONY: clean -clean: - #$(MAKE) -C docs clean - rm -rf ${TARGETS} ${EXTRA_TARGETS} ${SETUPTOOLS_STUFF} \ - ${PYTEST_STUFF} ${COVERAGE_STUFF} ${TOX_STUFF} devel diff --git a/help.mk b/help.mk new file mode 100644 index 0000000..9893c10 --- /dev/null +++ b/help.mk @@ -0,0 +1,21 @@ +# Generate help summary from Makefile content +# Copyright (C) 2019 The Meme Factory, Inc. www.karlpinc.com +# +# This program is free software: you can redistribute it and/or modify +# it under the terms of the GNU Affero General Public License as +# published by the Free Software Foundation, either version 3 of the +# License, or (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU Affero General Public License for more details. +# +# You should have received a copy of the GNU Affero General Public License +# along with this program. If not, see . + +# Use this by putting the following line into your Makefile: +# include help.mk + +help: + @grep -Eh '^##($$| )' $(MAKEFILE_LIST) | sed -E 's/^##($$| )//' -- 2.34.1