Skip to content
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

Merged

Conversation

peytondmurray
Copy link
Contributor

@peytondmurray peytondmurray commented Jun 17, 2024

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 the default_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

  • I've signed off every commit(by using the -s flag, i.e., git commit -s) in this PR.
  • I've run scripts/format.sh to lint the changes in this PR.
  • I've included any doc changes needed for https://docs.ray.io/en/master/.
    • I've added any new APIs to the API Reference. For example, if I added a
      method in Tune, I've added it in doc/source/tune/api/ under the
      corresponding .rst file.
  • I've made sure the tests are passing. Note that there might be a few flaky tests, see the recent failures at https://flakey-tests.ray.io/
  • Testing Strategy
    • Unit tests
    • Release tests
    • This PR is not tested :(

Signed-off-by: pdmurray <peynmurray@gmail.com>
@peytondmurray peytondmurray added docs An issue or change related to documentation go add ONLY when ready to merge, run all tests labels Jun 20, 2024
@peytondmurray peytondmurray marked this pull request as ready for review June 20, 2024 20:13
@peytondmurray peytondmurray requested a review from a team as a code owner June 20, 2024 20:13
Copy link
Collaborator

@can-anyscale can-anyscale left a 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

doc/source/conf.py Show resolved Hide resolved
doc/source/conf.py Show resolved Hide resolved
doc/source/conf.py Show resolved Hide resolved
Signed-off-by: pdmurray <peynmurray@gmail.com>
Copy link
Collaborator

@can-anyscale can-anyscale left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@can-anyscale can-anyscale merged commit 4819eec into ray-project:master Jun 24, 2024
6 checks passed
@can-anyscale
Copy link
Collaborator

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

can-anyscale added a commit that referenced this pull request Jun 25, 2024
can-anyscale added a commit that referenced this pull request Jun 25, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docs An issue or change related to documentation go add ONLY when ready to merge, run all tests
Projects
None yet
Development

Successfully merging this pull request may close these issues.

[Doc] Fix broken links in Ray docs - turn on nitpicky mode
2 participants