sphinx-contrib/sphinx-lintPublic

NotificationsYou must be signed in to change notification settings
Fork24
Star88

Check for stylistic and formal issues in .rst and .py files included in the documentation

License

View license

88 stars 24 forks Branches Tags Activity

Star

Notifications

You must be signed in to change notification settings

Branches Tags

Folders and files

Name		Name	Last commit message	Last commit date
Latest commit History 230 Commits
.github		.github
sphinxlint		sphinxlint
tests		tests
.coveragerc		.coveragerc
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
.pre-commit-hooks.yaml		.pre-commit-hooks.yaml
LICENSE		LICENSE
README.md		README.md
download-more-tests.sh		download-more-tests.sh
pyproject.toml		pyproject.toml
tox.ini		tox.ini

Repository files navigation

Sphinx Lint

Sphinx Lint is based onrstlint.py fromCPython.

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 arenot visible to sphinx-build.

Using Sphinx Lint

Here are some example invocations of Sphinx Lint from the command line:

sphinx-lint# check all dirs and filessphinx-lint file.rst# check a single filesphinx-lint docs# check a directorysphinx-lint -i venv# ignore a file/directorysphinx-lint -h# for more options

Sphinx Lint can also be used viapre-commit.We recommend using a configuration like this:

  -repo:https://github.com/sphinx-contrib/sphinx-lintrev:LATEST_SPHINXLINT_RELEASE_TAGhooks:      -id:sphinx-lint

Known issues

Currently Sphinx Lint can't work with tables, there's no understandingof howlinesplit works in tables, like:

+-----------------------------------------+-----------------------------+---------------+   | Method| Checks that| New in|+=========================================+=============================+===============+   |:meth:`assertEqual(a, b)| ``a == b``||   | <TestCase.assertEqual>`|||+-----------------------------------------+-----------------------------+---------------+

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 purereStructuredText point of view, one case usedocutils'spseudoxmlwriter, like:

$ docutils --writer=pseudoxml tests/fixtures/xpass/role-in-code-sample.rst<document source="tests/fixtures/xpass/role-in-code-sample.rst">    <paragraph>        Found in the pandas documentation, this is valid:    <bullet_list bullet="*">        <list_item>            <paragraph>                A pandas class (in the form                <literal>                    :class:`pandas.Series`                )        <list_item>            <paragraph>                A pandas method (in the form                <literal>                    :meth:`pandas.Series.sum`                )        <list_item>            <paragraph>                A pandas function (in the form                <literal>                    :func:`pandas.to_datetime`                )    <paragraph>        it's documenting roles using code samples (double backticks).

Releasing

Make sure that theCI tests passand optionally double-check locally with "friends projects" by running:
```
sh download-more-tests.shpython -m pytest
```
Go on theReleases page
Click "Draft a new release"
Click "Choose a tag"
Type the next vX.Y.Z version and select "Create new tag: vX.Y.Z on publish"
Leave the "Release title" blank (it will be autofilled)
Click "Generate release notes" and amend as required
Click "Publish release"
Check the taggedGitHub Actions buildhasdeployed to PyPI