DOC: Uniform block directive syntax. #44757
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
jreback
approved these changes
Dec 4, 2021
Yeah, I'm unsure how to currently check for that. I detected it automatically but the project that made me discover that is way too far from prime time to be added as a check. I could just grep for it and check the status code, but I'm afraid it would be a bit brittle. |
|
Could you add it as a pygrep check to the precommit config file? |
block directive syntax technically does not have space before the
double-colon.
While this seem to be accepted by docutils – but not documented,
this can throw off other RST parser/syntax highlighter.
Sometime they can see that as comments, sometime they give garbage out.
Plus this is really uncommon with 3 occurrences in pandas codebase with
space and 4800 without:
pandas[master] $ rg '\.\. \w+::' | wc -l
4853
Numpy and scipy used to have a few space in their block directive, but
current master/main branch of both should also be free of directive with
space before the double colon.
|
Done. |
|
lgtm. cc @MarcoGorelli |
MarcoGorelli
approved these changes
Dec 5, 2021
|
thanks @Carreau |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
block directive syntax technically does not have space before the
double-colon.
While this seem to be accepted by docutils – but not documented,
this can throw off other RST parser/syntax highlighter.
Sometime they can see that as comments, sometime they give garbage out.
Plus this is really uncommon with 3 occurrences in pandas codebase with
space and 4800 without:
Numpy and scipy used to have a few space in their block directive, but
current master/main branch of both should also be free of directive with
space before the double colon.
Note that this issue can be seen in the syntax highlighting of the diff of this PR itself, where the deleted lines are gray (comment), and added ones are blue/purple (directives)