Self-document Makefile

diff --git a/Makefile b/Makefile
index f11433ef2e818ac423511817830c4cc9f5c34933..b3a0cfbdb24dc1187aecb87199b43ced49b61427 100644 (file)
--- a/Makefile
+++ b/Makefile
@@ -32,78 +32,95 @@ PYTEST_STUFF = .cache src/pytest_common/__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
        hg 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_common 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,35 @@ 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
+
+#
+# Setup the virtual environments
+#
+
+# 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 ; \
@@ -126,18 +166,7 @@ devel/testenv: devel
               devel/testenv/bin/pip install -e '.[testing]' ; \
             )
 
-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 ; \
@@ -156,11 +185,7 @@ devel/pytest: devel dist
           ) ; \
        fi
 
-.PHONY: check
-check: devel/pytest
-       devel/pytest/bin/flake8 .
-       devel/pytest/bin/py.test --cov=pgwui_common tests
-
+# virtualenv for pudb
 devel/pudb: devel dist
        if [ ! -d devel/pudb ] ; then \
          ( ${VIRTUALENV} devel/pudb ; \
@@ -177,16 +202,3 @@ devel/pudb: devel dist
            devel/pudb/bin/pip install dist/pgwui_common-*.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 (file)
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 <https://www.gnu.org/licenses/>.
+
+# Use this by putting the following line into your Makefile:
+# include help.mk
+
+help:
+       @grep -Eh '^##($$| )' $(MAKEFILE_LIST) | sed -E 's/^##($$| )//'