diff --git a/.pre-commit-hooks.yaml b/.pre-commit-hooks.yaml index 8fda5eb14..61bc67b71 100644 --- a/.pre-commit-hooks.yaml +++ b/.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 - diff --git a/README.md b/README.md index dd8352119..afb5200ee 100644 --- a/README.md +++ b/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