Skip to content

Commit 6064e22

Browse files
authored
Add instructions for running lint and spellcheck tools locally (#2338)
1 parent 185aedc commit 6064e22

File tree

4 files changed

+128
-9
lines changed

4 files changed

+128
-9
lines changed

.github/CODEOWNERS

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,6 @@
77

88
# PEP infrastructure
99
.github/workflows/ @AA-Turner @CAM-Gerlach
10-
.pre-commit-config.yaml @CAM-Gerlach
1110
Makefile @AA-Turner
1211
requirements.txt @AA-Turner
1312

@@ -24,6 +23,15 @@ conf.py @AA-Turner
2423
contents.rst @AA-Turner
2524
generate_rss.py @AA-Turner
2625

26+
# Linting infrastructure
27+
.codespell/ @CAM-Gerlach @hugovk
28+
.codespellrc @CAM-Gerlach @hugovk
29+
.pre-commit-config.yaml @CAM-Gerlach @hugovk
30+
31+
# Git infrastructure
32+
.gitattributes @CAM-Gerlach
33+
.gitignore @CAM-Gerlach
34+
2735
pep-0001.txt @warsaw @ncoghlan
2836
pep-0001-process_flow.png @warsaw @ncoghlan
2937
pep-0001/ @warsaw @ncoghlan

CONTRIBUTING.rst

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,3 +51,88 @@ All interactions for this project are covered by the
5151
`PSF Code of Conduct <https://www.python.org/psf/codeofconduct/>`_. Everyone is
5252
expected to be open, considerate, and respectful of others no matter their
5353
position within the project.
54+
55+
56+
Run pre-commit linting locally
57+
------------------------------
58+
59+
You can run this repo's basic linting suite locally,
60+
either on-demand, or automatically against modified files
61+
whenever you commit your changes.
62+
63+
They are also run in CI, so you don't have to run them locally, though doing
64+
so will help you catch and potentially fix common mistakes before pushing
65+
your changes and opening a pull request.
66+
67+
This repository uses the `pre-commit <https://pre-commit.com/>`_ tool to
68+
install, configure and update a suite of hooks that check for
69+
common problems and issues, and fix many of them automatically.
70+
71+
If your system has ``make`` installed, you can run the pre-commit checkers
72+
on the full repo by running ``make lint``. This will
73+
install pre-commit in the current virtual environment if it isn't already,
74+
so make sure you've activated the environment you want it to use
75+
before running this command.
76+
77+
Otherwise, you can install pre-commit with
78+
79+
.. code-block:: console
80+
81+
python -m pip install pre-commit
82+
83+
(or your choice of installer), and then run the hooks on all the files
84+
in the repo with
85+
86+
.. code-block:: console
87+
88+
pre-commit run --all-files
89+
90+
or only on any files that have been modified but not yet committed with
91+
92+
.. code-block:: console
93+
94+
pre-commit run
95+
96+
If you would like pre-commit to run automatically against any modified files
97+
every time you commit, install the hooks with
98+
99+
.. code-block:: console
100+
101+
pre-commit install
102+
103+
Then, whenever you ``git commit``, pre-commit will run and report any issues
104+
it finds or changes it makes, and abort the commit to allow you to check,
105+
and if necessary correct them before committing again.
106+
107+
108+
Check and fix PEP spelling
109+
--------------------------
110+
111+
To check for common spelling mistakes in your PEP and automatically suggest
112+
corrections, you can run the codespell tool through pre-commit as well.
113+
114+
Like the linters, on a system with ``make`` available, it can be installed
115+
(in the currently-activated environment) and run on all files in the
116+
repository with a single command, ``make spellcheck``.
117+
118+
For finer control or on other systems, after installing pre-commit as in
119+
the previous section, you can run it against only the files
120+
you've modified and not yet committed with
121+
122+
.. code-block:: console
123+
124+
pre-commit run --hook-stage manual codespell
125+
126+
or against all files with
127+
128+
.. code-block:: console
129+
130+
pre-commit run --all-files --hook-stage manual codespell
131+
132+
**Note**: While fixing spelling mistakes as part of more substantive
133+
copyediting and proofreading of draft and active PEPs is okay,
134+
we generally advise against PRs that simply mass-correct minor typos on
135+
older PEPs that don't significantly impair meaning and understanding,
136+
as these tend to create a fairly high level of noise and churn for
137+
PEP readers, authors and editors relative to the amount of practical value
138+
they provide.

Makefile

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -52,11 +52,11 @@ package: all rss
5252
tar -C build -czf build/peps.tar.gz peps
5353

5454
lint:
55-
pre-commit --version > /dev/null || python3 -m pip install pre-commit
55+
pre-commit --version > /dev/null || $(PYTHON) -m pip install pre-commit
5656
pre-commit run --all-files
5757

5858
spellcheck:
59-
pre-commit --version > /dev/null || python3 -m pip install pre-commit
59+
pre-commit --version > /dev/null || $(PYTHON) -m pip install pre-commit
6060
pre-commit run --all-files --hook-stage manual codespell
6161

6262
# New Sphinx targets:

README.rst

Lines changed: 32 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -43,13 +43,39 @@ libraries in the ``pep0`` directory.
4343
Checking PEP formatting and rendering
4444
=====================================
4545

46-
Do not commit changes with bad formatting. To check the formatting of
47-
a PEP, use the Makefile. In particular, to generate HTML for PEP 9999,
48-
your source code should be in ``pep-9999.rst`` and the HTML will be
49-
generated to ``pep-9999.html`` by the command ``make pep-9999.html``.
50-
The default Make target generates HTML for all PEPs.
46+
Please don't commit changes with reStructuredText syntax errors that cause PEP
47+
generation to fail, or result in major rendering defects relative to what you
48+
intend. To check building the HTML output for your PEP (for example, PEP 12)
49+
using the current default docutils-based system, run the ``pep2html.py`` script
50+
with your PEP source file as its argument; e.g. for PEP 12,
5151

52-
If you don't have Make, use the ``pep2html.py`` script directly.
52+
.. code-block:: console
53+
54+
python pep2html.py pep-0012.rst
55+
56+
If you're on a system with ``make``, you can instead execute, e.g.,
57+
58+
.. code-block:: console
59+
60+
make pep-0012.rst
61+
62+
To generate HTML for all the PEPs, run the script/``make`` without a PEP
63+
file argument.
64+
65+
By default, this will output a file (e.g. ``pep-0012.html``) in the root
66+
directory, which you can view to see the HTML output of your PEP.
67+
Note that the custom CSS stylesheet is not used by default, so
68+
the PEP will look rather plain, but all the basic formatting produced by the
69+
reStructuredText syntax in your source file should be visible.
70+
71+
You can also view your PEP locally with the Sphinx-based builder,
72+
which will show the PEP exactly as it will appear on the preview
73+
of the new rendering system proposed in :pep:`676`;
74+
see `Rendering PEPs with Sphinx`_ for details.
75+
76+
Finally, you can check for and fix common linting and spelling issues,
77+
either on-demand or automatically as you commit, with our pre-commit suite.
78+
See the `Contributing Guide <./CONTRIBUTING.rst>`_ for details.
5379

5480

5581
Generating HTML for python.org

0 commit comments

Comments
 (0)