Add make requirements

HACKING.md

+Changing the Project's Python Dependencies
+------------------------------------------
+
+### To Add a New Dependency
+
+Add the dependency to the appropriate [`requirements/*.in`](requirements/)
+file(s) and then run:
+
+```terminal
+make requirements
+```
+
+### To Remove a Dependency
+
+Remove the dependency from the appropriate [`requirements/*.in`](requirements)
+file(s) and then run:
+
+```terminal
+make requirements
+```
+
+### To Upgrade or Downgrade a Dependency
+
+We rely on [Dependabot](https://github.com/dependabot) to keep all our
+dependencies up to date by sending automated pull requests to all our repos.
+But if you need to upgrade or downgrade a dependency manually you can do that
+locally.
+
+To upgrade a package to the latest version in all `requirements/*.txt` files:
+
+```terminal
+make requirements --always-make args='--upgrade-package <FOO>'
+```
+
+To upgrade or downgrade a package to a specific version:
+
+```terminal
+make requirements --always-make args='--upgrade-package <FOO>==<X.Y.Z>'
+```
+
+To upgrade **all** dependencies to their latest versions:
+
+```terminal
+make requirements --always-make args=--upgrade
+```
+

Makefile

@@ -54,6 +54,44 @@ format: node_modules/.uptodate
 checkformatting: node_modules/.uptodate
 	yarn run checkformatting
 
+# Tell make how to compile requirements/*.txt files.
+#
+# `touch` is used to pre-create an empty requirements/%.txt file if none
+# exists, otherwise tox crashes.
+#
+# $(subst) is used because in the special case of making requirements.txt we
+# actually need to touch dev.txt not requirements.txt and we need to run
+# `tox -e dev ...` not `tox -e requirements ...`
+#
+# $(basename $(notdir $@))) gets just the environment name from the
+# requirements/%.txt filename, for example requirements/foo.txt -> foo.
+requirements/%.txt: requirements/%.in
+	@touch -a $(subst requirements.txt,dev.txt,$@)
+	@tox -qe $(subst requirements,dev,$(basename $(notdir $@))) --run-command 'pip --quiet --disable-pip-version-check install pip-tools'
+	@tox -qe $(subst requirements,dev,$(basename $(notdir $@))) --run-command 'pip-compile --allow-unsafe --quiet $(args) $<'
+
+# Inform make of the dependencies between our requirements files so that it
+# knows what order to re-compile them in and knows to re-compile a file if a
+# file that it depends on has been changed.
+requirements/dev.txt: requirements/requirements.txt
+requirements/tests.txt: requirements/requirements.txt
+requirements/functests.txt: requirements/requirements.txt
+requirements/bddtests.txt: requirements/requirements.txt
+requirements/lint.txt: requirements/tests.txt requirements/functests.txt requirements/bddtests.txt
+
+# Add a requirements target so you can just run `make requirements` to
+# re-compile *all* the requirements files at once.
+#
+# This needs to be able to re-create requirements/*.txt files that don't exist
+# yet or that have been deleted so it can't just depend on all the
+# requirements/*.txt files that exist on disk $(wildcard requirements/*.txt).
+#
+# Instead we generate the list of requirements/*.txt files by getting all the
+# requirements/*.in files from disk ($(wildcard requirements/*.in)) and replace
+# the .in's with .txt's.
+.PHONY: requirements requirements/
+requirements requirements/: $(foreach file,$(wildcard requirements/*.in),$(basename $(file)).txt)
+
 .PHONY: sure
 sure: checkformatting lint test
 

requirements/checkdocs.in

+pip-tools
+myst-parser
+sphinx-autobuild
+sphinx
+sphinx_rtd_theme

requirements/checkdocs.txt

+#
+# This file is autogenerated by pip-compile with python 3.9
+# To update, run:
+#
+#    pip-compile --allow-unsafe requirements/checkdocs.in
+#
+alabaster==0.7.12
+    # via sphinx
+babel==2.10.3
+    # via sphinx
+build==0.8.0
+    # via pip-tools
+certifi==2022.6.15
+    # via requests
+charset-normalizer==2.1.0
+    # via requests
+click==8.1.3
+    # via pip-tools
+colorama==0.4.5
+    # via sphinx-autobuild
+docutils==0.17.1
+    # via
+    #   myst-parser
+    #   sphinx
+    #   sphinx-rtd-theme
+idna==3.3
+    # via requests
+imagesize==1.4.1
+    # via sphinx
+importlib-metadata==4.12.0
+    # via sphinx
+jinja2==3.1.2
+    # via
+    #   myst-parser
+    #   sphinx
+livereload==2.6.3
+    # via sphinx-autobuild
+markdown-it-py==2.1.0
+    # via
+    #   mdit-py-plugins
+    #   myst-parser
+markupsafe==2.1.1
+    # via jinja2
+mdit-py-plugins==0.3.0
+    # via myst-parser
+mdurl==0.1.1
+    # via markdown-it-py
+myst-parser==0.18.0
+    # via -r requirements/checkdocs.in
+packaging==21.3
+    # via
+    #   build
+    #   sphinx
+pep517==0.13.0
+    # via build
+pip-tools==6.8.0
+    # via -r requirements/checkdocs.in
+pygments==2.12.0
+    # via sphinx
+pyparsing==3.0.9
+    # via packaging
+pytz==2022.1
+    # via babel
+pyyaml==6.0
+    # via myst-parser
+requests==2.28.1
+    # via sphinx
+six==1.16.0
+    # via livereload
+snowballstemmer==2.2.0
+    # via sphinx
+sphinx==5.1.1
+    # via
+    #   -r requirements/checkdocs.in
+    #   myst-parser
+    #   sphinx-autobuild
+    #   sphinx-rtd-theme
+sphinx-autobuild==2021.3.14
+    # via -r requirements/checkdocs.in
+sphinx-rtd-theme==1.0.0
+    # via -r requirements/checkdocs.in
+sphinxcontrib-applehelp==1.0.2
+    # via sphinx
+sphinxcontrib-devhelp==1.0.2
+    # via sphinx
+sphinxcontrib-htmlhelp==2.0.0
+    # via sphinx
+sphinxcontrib-jsmath==1.0.1
+    # via sphinx
+sphinxcontrib-qthelp==1.0.3
+    # via sphinx
+sphinxcontrib-serializinghtml==1.1.5
+    # via sphinx
+tomli==2.0.1
+    # via
+    #   build
+    #   pep517
+tornado==6.2
+    # via livereload
+typing-extensions==4.3.0
+    # via myst-parser
+urllib3==1.26.11
+    # via requests
+wheel==0.37.1
+    # via pip-tools
+zipp==3.8.1
+    # via importlib-metadata
+
+# The following packages are considered to be unsafe in a requirements file:
+pip==22.2.1
+    # via pip-tools
+setuptools==63.2.0
+    # via pip-tools

requirements/docs.in

+pip-tools
 myst-parser
 sphinx-autobuild
 sphinx

requirements/docs.txt

 #
-# This file is autogenerated by pip-compile
+# This file is autogenerated by pip-compile with python 3.9
 # To update, run:
 #
-#    pip-compile requirements/docs.in
+#    pip-compile --allow-unsafe requirements/docs.in
 #
 alabaster==0.7.12
     # via sphinx
-attrs==20.3.0
-    # via markdown-it-py
-babel==2.9.1
+babel==2.10.3
     # via sphinx
-certifi==2020.12.5
+build==0.8.0
+    # via pip-tools
+certifi==2022.6.15
     # via requests
-chardet==4.0.0
+charset-normalizer==2.1.0
     # via requests
-colorama==0.4.4
+click==8.1.3
+    # via pip-tools
+colorama==0.4.5
     # via sphinx-autobuild
-docutils==0.16
+docutils==0.17.1
     # via
     #   myst-parser
     #   sphinx
     #   sphinx-rtd-theme
-idna==2.10
+idna==3.3
     # via requests
-imagesize==1.2.0
+imagesize==1.4.1
+    # via sphinx
+importlib-metadata==4.12.0
     # via sphinx
-jinja2==2.11.3
+jinja2==3.1.2
     # via
     #   myst-parser
     #   sphinx
 livereload==2.6.3
     # via sphinx-autobuild
-markdown-it-py==1.0.0
+markdown-it-py==2.1.0
     # via
     #   mdit-py-plugins
     #   myst-parser
-markupsafe==1.1.1
+markupsafe==2.1.1
     # via jinja2
-mdit-py-plugins==0.2.8
+mdit-py-plugins==0.3.0
     # via myst-parser
-myst-parser==0.14.0
-    # via -r docs.in
-packaging==20.9
-    # via sphinx
-pygments==2.9.0
+mdurl==0.1.1
+    # via markdown-it-py
+myst-parser==0.18.0
+    # via -r requirements/docs.in
+packaging==21.3
+    # via
+    #   build
+    #   sphinx
+pep517==0.13.0
+    # via build
+pip-tools==6.8.0
+    # via -r requirements/docs.in
+pygments==2.12.0
     # via sphinx
-pyparsing==2.4.7
+pyparsing==3.0.9
     # via packaging
-pytz==2021.1
+pytz==2022.1
     # via babel
-pyyaml==5.4.1
+pyyaml==6.0
     # via myst-parser
-requests==2.25.1
+requests==2.28.1
     # via sphinx
 six==1.16.0
     # via livereload
-snowballstemmer==2.1.0
+snowballstemmer==2.2.0
     # via sphinx
-sphinx-autobuild==2021.3.14
-    # via -r docs.in
-sphinx-rtd-theme==0.5.2
-    # via -r docs.in
-sphinx==3.5.4
+sphinx==5.1.1
     # via
-    #   -r docs.in
+    #   -r requirements/docs.in
     #   myst-parser
     #   sphinx-autobuild
     #   sphinx-rtd-theme
+sphinx-autobuild==2021.3.14
+    # via -r requirements/docs.in
+sphinx-rtd-theme==1.0.0
+    # via -r requirements/docs.in
 sphinxcontrib-applehelp==1.0.2
     # via sphinx
 sphinxcontrib-devhelp==1.0.2
     # via sphinx
-sphinxcontrib-htmlhelp==1.0.3
+sphinxcontrib-htmlhelp==2.0.0
     # via sphinx
 sphinxcontrib-jsmath==1.0.1
     # via sphinx
 sphinxcontrib-qthelp==1.0.3
     # via sphinx
-sphinxcontrib-serializinghtml==1.1.4
+sphinxcontrib-serializinghtml==1.1.5
     # via sphinx
-tornado==6.1
+tomli==2.0.1
+    # via
+    #   build
+    #   pep517
+tornado==6.2
     # via livereload
-urllib3==1.26.5
+typing-extensions==4.3.0
+    # via myst-parser
+urllib3==1.26.11
     # via requests
+wheel==0.37.1
+    # via pip-tools
+zipp==3.8.1
+    # via importlib-metadata
 
 # The following packages are considered to be unsafe in a requirements file:
-# setuptools
+pip==22.2.1
+    # via pip-tools
+setuptools==63.2.0
+    # via pip-tools

tox.ini

@@ -9,11 +9,9 @@ requires =
 [testenv]
 skip_install = true
 deps =
-    {docs,checkdocs}: -r requirements/docs.txt
-    {env:EXTRA_DEPS:}
+    -r requirements/{env:TOX_ENV_NAME}.txt
 passenv =
     HOME
-    EXTRA_DEPS
 commands =
     docs: sphinx-autobuild -qT --open-browser -b dirhtml -d {envdir}/doctrees docs {envdir}/html
     checkdocs: sphinx-build -qTWn -b dirhtml -d {envdir}/doctrees docs {envdir}/html