-
Notifications
You must be signed in to change notification settings - Fork 5.8k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
[Doc] Turn on nitpicky mode #46103
[Doc] Turn on nitpicky mode #46103
Conversation
Signed-off-by: pdmurray <peynmurray@gmail.com>
afc2a47
to
ba4a641
Compare
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
thanks for working on this
Signed-off-by: pdmurray <peynmurray@gmail.com>
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
this is breaking doc build in master i believe https://buildkite.com/ray-project/postmerge/builds/5103#01904cb8-8310-456d-bcd2-146a52e30d93; reverting to unblock |
This reverts commit 4819eec.
Why are these changes needed?
This PR prevents developers from breaking internal sphinx references by causing the docs build to fail if a broken reference is found.
Previously, broken references would simply be rendered as inline code but now they will raise an exception during the build process. It will be the responsibility of the developer who changes/adds/removes APIs or documentation to ensure the documentation is updated accordingly.
Furthermore, single backticks (
`
) will now default to just being rendered as code; previously Sphinx considered anything in single backticks a reference. Most developers who touch documentation are familiar with markdown rather than RST, and use single backticks to denote code although it is not valid RST syntax for code (RST uses double backticks). As a result, there are many many places in the documentation that use single backticks to mean code, and it would be impractical to expect contributors to adhere strictly to RST syntax when everyone is used to markdown. So instead we modify thedefault_role
to eliminate this problem entirely, and treat anything in single backticks as code.Related issue number
Closes #39658. Currently blocked by #46102; will mark this as ready once that PR is merged.
Checks
git commit -s
) in this PR.scripts/format.sh
to lint the changes in this PR.method in Tune, I've added it in
doc/source/tune/api/
under thecorresponding
.rst
file.