https://github.com/sphinx-contrib/sphinx-lint
Check for stylistic and formal issues in .rst and .py files included in the documentation
https://github.com/sphinx-contrib/sphinx-lint
docs documentation lint linter python restructuredtext rst sphinx
Last synced: about 1 month ago
JSON representation
Check for stylistic and formal issues in .rst and .py files included in the documentation
- Host: GitHub
- URL: https://github.com/sphinx-contrib/sphinx-lint
- Owner: sphinx-contrib
- License: other
- Created: 2022-01-23T15:44:47.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2024-03-23T12:03:32.000Z (about 1 year ago)
- Last Synced: 2024-05-01T18:33:56.773Z (about 1 year ago)
- Topics: docs, documentation, lint, linter, python, restructuredtext, rst, sphinx
- Language: Python
- Homepage: https://pypi.org/project/sphinx-lint/
- Size: 279 KB
- Stars: 61
- Watchers: 11
- Forks: 17
- Open Issues: 31
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# Sphinx Lint
[
](https://pypi.org/project/sphinx-lint)
[](https://github.com/sphinx-contrib/sphinx-lint/actions)
Sphinx Lint is based on [rstlint.py from
CPython](https://github.com/python/cpython/blob/e0433c1e7/Doc/tools/rstlint.py).
## What is Sphinx Lint, what is it not?
Sphinx Lint should:
- be reasonably fast so it's comfortable to use as a linter in your editor.
- be usable on a single file.
- not give any false positives (probably a utopia, but let's try).
- not spend too much effort finding errors that sphinx-build already finds (or can easily find).
- focus on finding errors that are **not** visible to sphinx-build.
## Using Sphinx Lint
Here are some example invocations of Sphinx Lint from the command line:
```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
```
## Known issues
Currently Sphinx Lint can't work with tables, there's no understanding
of how `linesplit` works in tables, like:
```rst
+-----------------------------------------+-----------------------------+---------------+
| Method | Checks that | New in |
+=========================================+=============================+===============+
| :meth:`assertEqual(a, b) | ``a == b`` | |
| ` | | |
+-----------------------------------------+-----------------------------+---------------+
```
as Sphinx Lint works line by line it will inevitably think the `:meth:` role is not closed properly.
To avoid false positives, some rules are skipped if we're in a table.
## Contributing
A quick way to test if some syntax is valid from a pure
reStructuredText point of view, one case use `docutils`'s `pseudoxml`
writer, like:
```text
$ docutils --writer=pseudoxml tests/fixtures/xpass/role-in-code-sample.rst
Found in the pandas documentation, this is valid:
A pandas class (in the form
:class:`pandas.Series`
)
A pandas method (in the form
:meth:`pandas.Series.sum`
)
A pandas function (in the form
:func:`pandas.to_datetime`
)
it's documenting roles using code samples (double backticks).
```
## Releasing
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
As this script was in the CPython repository the license is the Python
Software Foundation Licence Version 2, see the LICENSE file for a full
version.