Improve usability of Sphinx Lint with pre-commit (#94)

Co-authored-by: Hugo van Kemenade <[email protected]>

Author: AlexWaygood

.pre-commit-hooks.yaml

@@ -1,7 +1,8 @@
 - id: sphinx-lint
-  name: Sphinx lint
-  description: 'Searches for common typos in sphinx-flavored rst files.'
-  files: '\.rst$'
+  name: Sphinx Lint
+  description: 'Searches for common problems in Sphinx-flavored reST files'
+  types: [rst]
+  # Defer to pre-commit on the best way to delegate resources across available cores
+  args: [--jobs=1]
   entry: sphinx-lint
   language: python
-

README.md

@@ -12,7 +12,7 @@ CPython](https://github.com/python/cpython/blob/e0433c1e7/Doc/tools/rstlint.py).
 
 ## What is Sphinx Lint, what is it not?
 
-`sphinx-lint` should:
+Sphinx Lint should:
 
 - be reasonably fast so it's comfortable to use as a linter in your editor.
 - be usable on a single file.
@@ -23,7 +23,7 @@ CPython](https://github.com/python/cpython/blob/e0433c1e7/Doc/tools/rstlint.py).
 
 ## Using Sphinx Lint
 
-To use Sphinx Lint, run:
+Here are some example invocations of Sphinx Lint from the command line:
 
 ```sh
 sphinx-lint           # check all dirs and files
@@ -41,17 +41,8 @@ We recommend using a configuration like this:
     rev: LATEST_SPHINXLINT_RELEASE_TAG
     hooks:
       - id: sphinx-lint
-        args: [--jobs=1]
-        types: [rst]
 ```
 
-In particular, note that the `--jobs=1` flag is recommended for use with pre-commit.
-By default, Sphinx Lint uses `multiprocessing` to lint multiple files simultaneously,
-but this interacts poorly with pre-commit, which also attempts to use multiprocessing,
-leading to resource contention. Adding `--jobs=1` tells Sphinx Lint not to use
-multiprocessing itself, deferring to pre-commit on the best way to delegate resources
-across available cores.
-
 
 ## Known issues