Add instructions for running lint and spellcheck tools locally (#2338)

.github/CODEOWNERS

@@ -7,7 +7,6 @@
 
 # PEP infrastructure
 .github/workflows/      @AA-Turner @CAM-Gerlach
-.pre-commit-config.yaml @CAM-Gerlach
 Makefile                @AA-Turner
 requirements.txt        @AA-Turner
 
@@ -24,6 +23,15 @@ conf.py                 @AA-Turner
 contents.rst            @AA-Turner
 generate_rss.py         @AA-Turner
 
+# Linting infrastructure
+.codespell/             @CAM-Gerlach @hugovk
+.codespellrc            @CAM-Gerlach @hugovk
+.pre-commit-config.yaml @CAM-Gerlach @hugovk
+
+# Git infrastructure
+.gitattributes          @CAM-Gerlach
+.gitignore              @CAM-Gerlach
+
 pep-0001.txt  @warsaw @ncoghlan
 pep-0001-process_flow.png  @warsaw @ncoghlan
 pep-0001/     @warsaw @ncoghlan

CONTRIBUTING.rst

@@ -51,3 +51,88 @@ All interactions for this project are covered by the
 `PSF Code of Conduct <https://www.python.org/psf/codeofconduct/>`_. Everyone is
 expected to be open, considerate, and respectful of others no matter their
 position within the project.
+
+
+Run pre-commit linting locally
+------------------------------
+
+You can run this repo's basic linting suite locally,
+either on-demand, or automatically against modified files
+whenever you commit your changes.
+
+They are also run in CI, so you don't have to run them locally, though doing
+so will help you catch and potentially fix common mistakes before pushing
+your changes and opening a pull request.
+
+This repository uses the `pre-commit <https://pre-commit.com/>`_ tool to
+install, configure and update a suite of hooks that check for
+common problems and issues, and fix many of them automatically.
+
+If your system has ``make`` installed, you can run the pre-commit checkers
+on the full repo by running ``make lint``. This will
+install pre-commit in the current virtual environment if it isn't already,
+so make sure you've activated the environment you want it to use
+before running this command.
+
+Otherwise, you can install pre-commit with
+
+.. code-block:: console
+
+    python -m pip install pre-commit
+
+(or your choice of installer), and then run the hooks on all the files
+in the repo with
+
+.. code-block:: console
+
+    pre-commit run --all-files
+
+or only on any files that have been modified but not yet committed with
+
+.. code-block:: console
+
+    pre-commit run
+
+If you would like pre-commit to run automatically against any modified files
+every time you commit, install the hooks with
+
+.. code-block:: console
+
+    pre-commit install
+
+Then, whenever you ``git commit``, pre-commit will run and report any issues
+it finds or changes it makes, and abort the commit to allow you to check,
+and if necessary correct them before committing again.
+
+
+Check and fix PEP spelling
+--------------------------
+
+To check for common spelling mistakes in your PEP and automatically suggest
+corrections, you can run the codespell tool through pre-commit as well.
+
+Like the linters, on a system with ``make`` available, it can be installed
+(in the currently-activated environment) and run on all files in the
+repository with a single command, ``make spellcheck``.
+
+For finer control or on other systems, after installing pre-commit as in
+the previous section, you can run it against only the files
+you've modified and not yet committed with
+
+.. code-block:: console
+
+    pre-commit run --hook-stage manual codespell
+
+or against all files with
+
+.. code-block:: console
+
+    pre-commit run --all-files --hook-stage manual codespell
+
+**Note**: While fixing spelling mistakes as part of more substantive
+copyediting and proofreading of draft and active PEPs is okay,
+we generally advise against PRs that simply mass-correct minor typos on
+older PEPs that don't significantly impair meaning and understanding,
+as these tend to create a fairly high level of noise and churn for
+PEP readers, authors and editors relative to the amount of practical value
+they provide.

Makefile

@@ -52,11 +52,11 @@ package: all rss
 	tar -C build -czf build/peps.tar.gz peps
 
 lint:
-	pre-commit --version > /dev/null || python3 -m pip install pre-commit
+	pre-commit --version > /dev/null || $(PYTHON) -m pip install pre-commit
 	pre-commit run --all-files
 
 spellcheck:
-	pre-commit --version > /dev/null || python3 -m pip install pre-commit
+	pre-commit --version > /dev/null || $(PYTHON) -m pip install pre-commit
 	pre-commit run --all-files --hook-stage manual codespell
 
 # New Sphinx targets:

README.rst

@@ -43,13 +43,39 @@ libraries in the ``pep0`` directory.
 Checking PEP formatting and rendering
 =====================================
 
-Do not commit changes with bad formatting.  To check the formatting of
-a PEP, use the Makefile.  In particular, to generate HTML for PEP 9999,
-your source code should be in ``pep-9999.rst`` and the HTML will be
-generated to ``pep-9999.html`` by the command ``make pep-9999.html``.
-The default Make target generates HTML for all PEPs.
+Please don't commit changes with reStructuredText syntax errors that cause PEP
+generation to fail, or result in major rendering defects relative to what you
+intend. To check building the HTML output for your PEP (for example, PEP 12)
+using the current default docutils-based system, run the ``pep2html.py`` script
+with your PEP source file as its argument; e.g. for PEP 12,
 
-If you don't have Make, use the ``pep2html.py`` script directly.
+.. code-block:: console
+
+    python pep2html.py pep-0012.rst
+
+If you're on a system with ``make``, you can instead execute, e.g.,
+
+.. code-block:: console
+
+    make pep-0012.rst
+
+To generate HTML for all the PEPs, run the script/``make`` without a PEP
+file argument.
+
+By default, this will output a file (e.g. ``pep-0012.html``) in the root
+directory, which you can view to see the HTML output of your PEP.
+Note that the custom CSS stylesheet is not used by default, so
+the PEP will look rather plain, but all the basic formatting produced by the
+reStructuredText syntax in your source file should be visible.
+
+You can also view your PEP locally with the Sphinx-based builder,
+which will show the PEP exactly as it will appear on the preview
+of the new rendering system proposed in :pep:`676`;
+see `Rendering PEPs with Sphinx`_ for details.
+
+Finally, you can check for and fix common linting and spelling issues,
+either on-demand or automatically as you commit, with our pre-commit suite.
+See the `Contributing Guide <./CONTRIBUTING.rst>`_ for details.
 
 
 Generating HTML for python.org