Add a Linter

[cschan1828]

Propose to integrate a linter with CI and/or Makefile. It would help translators detect common rST syntax errors and focus more on semantics.

[cschan1828]

Feel free to leave a message if you are interested in this topic.

[cschan1828]

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]

What additional checkers would you like to add?

[cschan1828]

Some common mistakes (not limited to):

• handle :: in a wrong way.
• Full-width and half-width parentheses, and the blank spaces. If the parentheses do not contain Mandarin characters, half-width parentheses should be used, and there should be a space before the preceding character. (For example, 樣本平均數提供了對真實母體平均數的不偏估計 (unbiased estimate)，所以...)
• A space before a Mandarin character may need to be removed and replaced with \\ in rST syntax. (For example, 平均值強烈受到<Insert \\ here> 離群值 (outliers) https://en.wikipedia.org/wiki/Outlier`_ 的影響。
• Inconsistent with original text in punctuation marks. (For example, 'localhost' was translated to localhost. 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]

sphinx-lint has a mechanism to enable/disable specific checkers. One option is to add (some of) the checks you mentioned in sphinx-lint itself, 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-lint to load custom checkers.

[cschan1828]

Thanks @ezio-melotti's contribution. We now have a basic linter now. Use VERSION=3.12 make lint to validate your reST syntax.

So far, two files have not passed the linter check:

whatsnew/3.2.po:1536: default role used (hint: for inline literals, use double backticks) (default-role)
whatsnew/3.10.po:2569: default role used (hint: for inline literals, use double backticks) (default-role)

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]

whatsnew/3.2.po:1536: default role used (hint: for inline literals, use double backticks) (default-role)
whatsnew/3.10.po:2569: default role used (hint: for inline literals, use double backticks) (default-role)

I created two PRs to fix these, which appeared to be actual errors:

• Fix reST markup in 3.2.po #743
• Fix reST markup in 3.10.po #744

Next Step: Evaluate if it can be integrated with CI.

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-lint to handle them correctly.

[cschan1828]

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]

Once linter is integrated with CI. We can close this issue.

[ezio-melotti]

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]

@ezio-melotti Sure. Please help on this. Thank you!

[cschan1828]

Currently, sphinx-lint may not fully replace sphinx-build 100%.
I mistyped :exc:ValueError as :exec:ValueError, which caused a build failure, but sphinx-lint didn't catch it.

[ezio-melotti]

sphinx-lint is not supposed to replace sphinx-build, but complement it. sphinx-lint will also not report some of the errors that sphinx-build detects while building the docs.