From 86b83418a9686836cff0607dc620bd34202cbffe Mon Sep 17 00:00:00 2001
From: John Whitlock <jwhitlock@mozilla.com>
Date: Mon, 24 Jun 2024 17:34:19 -0500
Subject: [PATCH] Update docs for typing, etc.

---
 docs/contributing.rst | 66 +++++++++++++++++++++++++++++++++++++++++--
 pyproject.toml        |  1 +
 2 files changed, 65 insertions(+), 2 deletions(-)

diff --git a/docs/contributing.rst b/docs/contributing.rst
index e48df57..254287e 100644
--- a/docs/contributing.rst
+++ b/docs/contributing.rst
@@ -8,6 +8,22 @@ Patches are more than welcome! You can find the issue tracker `on GitHub
 <https://github.com/mozilla/django-csp/issues>`_ and we'd love pull
 requests.
 
+Setup
+=====
+To install all the requirements (probably into a virtualenv_):
+
+.. code-block:: bash
+
+    pip install -e .
+    pip install -e ".[dev]"
+
+This installs:
+
+* All the text requirements
+* All the typing requirements
+* pre-commit_, for checking styles
+* tox_, for running tests against multiple environments
+* Sphinx_ and document building requirements
 
 Style
 =====
@@ -44,9 +60,55 @@ To run the tests with coverage and get a report, use the following command:
 
     pytest --cov=csp --cov-config=.coveragerc
 
+To run the tests like Github Actions does, you'll need pyenv_:
+
+.. code-block:: bash
+
+    pyenv install 3.8 3.9 3.10 3.11 3.12 pypy3.8 pypy3.9 pypy3.10
+    pyenv local 3.8 3.9 3.10. 3.11 3.12 pypy3.8 pypy3.9 pypy3.10
+    pip install -e ".[dev]"  # installs tox
+    tox                # run sequentially
+    tox run-parallel   # run in parallel, may cause issues on coverage step
+    tox -e 3.12-4.2.x  # run tests on Python 3.12 and Django 4.x
+    tox --listenvs     # list all the environments
+
+Type Checking
+=============
+
+New code should have type annotations and pass mypy_ in strict mode. Use the
+typing syntax available in the earliest supported Python version 3.8.
+
+To check types:
+
+.. code-block:: bash
+
+    pip install -e ".[typing]"
+    mypy .
+
+If you make a lot of changes, it can help to clear the mypy cache:
+
+.. code-block:: bash
+
+    mypy --no-incremental .
+
+Updating Documentation
+======================
+
+To rebuild documentation locally:
+
+.. code-block:: bash
+
+    pip install -e ".[dev]"
+    cd docs
+    make html
+    open _build/html/index.html  # On macOS
 
 .. _PEP8: http://www.python.org/dev/peps/pep-0008/
+.. _Sphinx: https://www.sphinx-doc.org/en/master/index.html
+.. _mypy: https://mypy.readthedocs.io/en/stable/
+.. _pre-commit: https://pre-commit.com/#install
+.. _pyenv: https://github.com/pyenv/pyenv
+.. _pytest: https://pytest.org/latest/usage.html
 .. _ruff: https://pypi.org/project/ruff/
+.. _tox: https://tox.wiki/en/stable/
 .. _virtualenv: http://www.virtualenv.org/
-.. _pytest: https://pytest.org/latest/usage.html
-.. _pre-commit: https://pre-commit.com/#install
diff --git a/pyproject.toml b/pyproject.toml
index c4c3e4f..1dd0b41 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -52,6 +52,7 @@ optional-dependencies.dev = [
   "Sphinx",
   "sphinx_rtd_theme",
   "tox",
+  "tox-gh-actions",
   "types-setuptools",
 ]
 optional-dependencies.jinja2 = [