Repository navigation
Add a Linter #494
Description
Propose to integrate a linter with CI and/or Makefile. It would help translators detect common rST syntax errors and focus more on semantics.
{{ message }}
Propose to integrate a linter with CI and/or Makefile. It would help translators detect common rST syntax errors and focus more on semantics.
Activity
cschan1828 commentedon Jul 20, 2023
Feel free to leave a message if you are interested in this topic.
cschan1828 commentedon Jul 23, 2023
sphinx-lint may be a good choice. However, currently it doesn't support the customized checkers that we need for zh-tw translation. I am considering whether we need to fork sphinx-lint for our own development.
ezio-melotti commentedon Jul 23, 2023
What additional checkers would you like to add?
cschan1828 commentedon Jul 23, 2023
Some common mistakes (not limited to):
::in a wrong way.\\in rST syntax. (For example, 平均值強烈受到<Insert\\here> 離群值 (outliers) https://en.wikipedia.org/wiki/Outlier`_ 的影響。'localhost'was translated tolocalhost. The ' symbol was missing.)These features are specific to zh-tw, so I am wondering whether we need to implement this feature for ourselves use.
ezio-melotti commentedon Jul 23, 2023
sphinx-linthas a mechanism to enable/disable specific checkers. One option is to add (some of) the checks you mentioned insphinx-lintitself, but keep them disabled by default so that they don't affect other projects.This will have to be evaluated on a case-by-case basis, since some of these checkers could be useful for other CJK documentations or other translation projects as well, making them a valuable addition to the project.
For checkers that are too specific, a long-term solution would be to add a mechanism to
sphinx-lintto load custom checkers.cschan1828 commentedon Dec 9, 2023
Thanks @ezio-melotti's contribution. We now have a basic linter now. Use
VERSION=3.12 make lintto validate your reST syntax.So far, two files have not passed the linter check:
These seem like false alarms to me. As a workaround, we can exclude these two files from sphinx-lint. In the long term, we still need to understand if we can add any rules to handle this.
Next Step: Evaluate if it can be integrated with CI.
ezio-melotti commentedon Dec 9, 2023
I created two PRs to fix these, which appeared to be actual errors:
If those PRs fix the issues and there are no false positives, I think it can be integrated. Should any false positive pop-up in the future, we can temporarily exclude those files and/or fix
sphinx-lintto handle them correctly.cschan1828 commentedon Dec 9, 2023
Yes, that's right. Absolutely, it is much faster and more flexible for check processes development.
Note that the current method is still not able to catch all the common mistakes I mentioned in this thread (just like the existing process). Maybe we can explore some ways to add some customized rules specific to CJK text. I will create another ticket for tracking.
cschan1828 commentedon Dec 9, 2023
Once linter is integrated with CI. We can close this issue.
ezio-melotti commentedon Dec 9, 2023
Do you want me to prepare a PR?
I already did the CI integration in #496, so it's just a matter to recreate that part of the PR.
@mattwang44 also suggested using a pre-commit hook in #496 (review)
cschan1828 commentedon Dec 9, 2023
@ezio-melotti Sure. Please help on this. Thank you!
cschan1828 commentedon Dec 10, 2023
Currently, sphinx-lint may not fully replace sphinx-build 100%.
I mistyped :exc:
ValueErroras :exec:ValueError, which caused a build failure, but sphinx-lint didn't catch it.ezio-melotti commentedon Dec 14, 2023
sphinx-lintis not supposed to replacesphinx-build, but complement it.sphinx-lintwill also not report some of the errors thatsphinx-builddetects while building the docs.mattwang44 commentedon Jul 12, 2025
I believe sphinx-lint has seen substantial enhancements thanks to contributions from the community. Over the past year I’ve come to rely on sphinx-lint locally to catch syntax issues before opening any PRs, and it’s saved me a lot of time.
If no objection, I'd like to add sphinx-lint into the CI github action workflow (e.g.
uvx sphinx-lint **/*.rst).ezio-melotti commentedon Jul 14, 2025
Note that there is already a
linttarget in theMakefilethat could be used for this (also handles the installation, so you could just callmake lintin the workflow). Adding it to precommit should also be fine.StanFromIreland commentedon Aug 14, 2025
I suggest you look into the python-docs-translations/transifex-automation's sample workflows. They also have some docs here, they will make setup quite simple.