amoeba commented on issue #41611:
URL: https://github.com/apache/arrow/issues/41611#issuecomment-2103592192
The current docs violates just six of the 22 sphinx-lint rules. Of these,
most are useful and catch real issues. For each, I've noted which I think we
should and shouldn't enable:
- dangling-hyphen
- No. This is meant to catch hyphens breaking up long words for hard
wrapping but we use dangling hyphens for some anchors and our use looks legit.
- missing-space-after-literal
- Yes. This caught a bug in
https://arrow.apache.org/docs/java/algorithm.html and will help us catch future
issues.
- horizontal-tab
- Yes. This seems like a good catch since tabs don't get treated correctly
in HTML anyway and it makes it hard to know whether the source will render
correctly.
- missing-final-newline
- Yes. A bit nitpicky but it makes things more regular which should avoid
noise in diffs.
- missing-underscore-after-hyperlink
- Yes. Caught a broken link in
https://arrow.apache.org/docs/format/Integration.html.
- trailing-whitespace
- Yes. Again a bit nitpicky but it makes the docs more regular which
avoids diff noise.
- unbalanced-inline-literals-delimiters
- Yes. This catches real issues where authors forget to close their
literals.
I think we could get away with just disabling `dangling-hyphen` and enabling
all other checks. I'll still go through the other checks to make sure we don't
enable something we don't want but, since we don't violate most of the rules,
we can disable any we find that don't add value in the future. I'll update here
once I do that.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
