From 881f0d540d14393753e67dee700d8104317958b0 Mon Sep 17 00:00:00 2001 From: Ezio Melotti Date: Fri, 13 Oct 2023 16:56:13 +0200 Subject: [PATCH 1/5] Add link to changelog on pyproject.toml/PyPI (#92) --- pyproject.toml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/pyproject.toml b/pyproject.toml index ca6cbdb01..5f4d12743 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -31,7 +31,8 @@ dynamic = ["version"] [project.urls] -repository = "https://github.com/sphinx-contrib/sphinx-lint" +Repository = "https://github.com/sphinx-contrib/sphinx-lint" +Changelog = "https://github.com/sphinx-contrib/sphinx-lint/releases" [project.scripts] sphinx-lint = "sphinxlint.__main__:main" From 4cecfc7deeab1c0e5876e986cfbecc66f5bd0332 Mon Sep 17 00:00:00 2001 From: Alex Waygood Date: Fri, 13 Oct 2023 17:10:04 +0200 Subject: [PATCH 2/5] Add docs on how best to use sphinx-lint with pre-commit (#90) Co-authored-by: Hugo van Kemenade Co-authored-by: Ezio Melotti --- README.md | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/README.md b/README.md index 0cca15ce5..a40b01438 100644 --- a/README.md +++ b/README.md @@ -21,6 +21,37 @@ CPython](https://github.com/python/cpython/blob/e0433c1e7/Doc/tools/rstlint.py). - focus on finding errors that are **not** visible to sphinx-build. +## Using Sphinx Lint + +To use Sphinx Lint, run: + +```sh +sphinx-lint # check all dirs and files +sphinx-lint file.rst # check a single file +sphinx-lint docs # check a directory +sphinx-lint -i venv # ignore a file/directory +sphinx-lint -h # for more options + +Sphinx Lint can also be used via [pre-commit](https://pre-commit.com). +We recommend using a configuration like this: + +```yaml + - repo: https://github.com/sphinx-contrib/sphinx-lint + 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 Currently Sphinx Lint can't work with tables, there's no understanding From 6b758fd9f63bc8a53fd6a6177dc64f2c349701c5 Mon Sep 17 00:00:00 2001 From: Ezio Melotti Date: Fri, 13 Oct 2023 17:21:34 +0200 Subject: [PATCH 3/5] Update release instructions in README.md (#89) * Update release instructions in README.md * Update history link. Co-authored-by: Alex Waygood * Add quotes around our friends projects Co-authored-by: Alex Waygood * Fix wrong sentence. --------- Co-authored-by: Alex Waygood --- README.md | 31 +++++++++++++++---------------- 1 file changed, 15 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index a40b01438..cd3bcbc88 100644 --- a/README.md +++ b/README.md @@ -108,22 +108,21 @@ $ docutils --writer=pseudoxml tests/fixtures/xpass/role-in-code-sample.rst ## Releasing -First test with friends projects by running: - - sh download-more-tests.sh - python -m pytest - -Bump the version in `sphinxlint.py`, commit, tag, push: - - git tag v0.6.5 - git push - git push --tags - -To release on PyPI run: - - python -m pip install --upgrade build twine - python -m build - python -m twine upload dist/* +1. Make sure that the [CI tests pass](https://github.com/sphinx-contrib/sphinx-lint/actions) + and optionally double-check locally with "friends projects" by running: + + sh download-more-tests.sh + python -m pytest +2. Go on the [Releases page](https://github.com/sphinx-contrib/sphinx-lint/releases) +3. Click "Draft a new release" +4. Click "Choose a tag" +5. Type the next vX.Y.Z version and select "Create new tag: vX.Y.Z on publish" +6. Leave the "Release title" blank (it will be autofilled) +7. Click "Generate release notes" and amend as required +8. Click "Publish release" +9. Check the tagged + [GitHub Actions build](https://github.com/sphinx-contrib/sphinx-lint/actions/workflows/deploy.yml) + has [deployed to PyPI](https://pypi.org/project/sphinx-lint/#history) ## License From 84d17a721126f4fb974a755c6cf7e8e8e71e05f6 Mon Sep 17 00:00:00 2001 From: Jared Dillard Date: Fri, 13 Oct 2023 21:45:23 -0700 Subject: [PATCH 4/5] Fix sh code block in README (#93) It wasn't closed properly --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index cd3bcbc88..dd8352119 100644 --- a/README.md +++ b/README.md @@ -31,6 +31,7 @@ sphinx-lint file.rst # check a single file sphinx-lint docs # check a directory sphinx-lint -i venv # ignore a file/directory sphinx-lint -h # for more options +``` Sphinx Lint can also be used via [pre-commit](https://pre-commit.com). We recommend using a configuration like this: From dbccac04ae71d24a8ba373286fd8326ae43716ba Mon Sep 17 00:00:00 2001 From: Alex Waygood Date: Sun, 15 Oct 2023 17:50:01 +0100 Subject: [PATCH 5/5] Improve usability of Sphinx Lint with pre-commit (#94) Co-authored-by: Hugo van Kemenade --- .pre-commit-hooks.yaml | 9 +++++---- README.md | 13 ++----------- 2 files changed, 7 insertions(+), 15 deletions(-) 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