[CI/Build] Add sphinx/rst linter for docs

[rafvasq]

Currently there's no linter/style checker for the docs, this PR offers sphinx-lint to clean up stylistic and formatting errors that don't show up in the build.

[github-actions]

👋 Hi! Thank you for contributing to the vLLM project.
Just a reminder: PRs would not trigger full CI run by default. Instead, it would only run fastcheck CI which starts running only a small and essential subset of CI tests to quickly catch errors. You can run other CI tests on top of those by going to your fastcheck build on Buildkite UI (linked in the PR checks section) and unblock them. If you do not have permission to unblock, ping simon-mo or khluu to add you in our Buildkite org.

Once the PR is approved and ready to go, your PR reviewer(s) can run CI to test the changes comprehensively before merging.

To run CI, PR reviewers can do one of these:

• Add ready label to the PR
• Enable auto-merge.

🚀

[russellb]

I took a look at this same linter earlier this week. I didn't post it because it didn't seem to find anything interesting. All I had to disable to get it to run cleanly was:

sphinx-lint --disable trailing-whitespace,missing-final-newline docs

and neither of those warnings seem worth enforcing. My conclusion was that the most important issues are already caught as part of the docs build, which already happens on every PR.

In other words, this didn't seem worth it to me. Did you find anything I missed?

[rafvasq]

That's fair, I totally understand if those particular warnings aren't worth enforcing. A few things I'd advocate as helpful for future documentation changes though are the specific the backticks, spaces, underscores needed by things like hyperlinks and roles which don't break the doc build. You'd have to wait for the doc build to complete and only catch these during review.

`GPTQ <https://arxiv.org/abs/2210.17323>`_

:class:`~vllm.LLM`

[russellb]

In other words, it's quicker to find issues using this during the dev (writing) phase than doing full doc builds? I'd agree with that. To make that a little easier, I'd include it in format.sh, as well. I have that in a branch if you want to cherry-pick it to your branch.

https://github.com/vllm-project/vllm/compare/main...russellb:vllm:rst-linting?expand=1

[russellb]

if you pull in my commit, I would change this to:

Suggested change

	pip install sphinx-lint
	pip install -r requirements-lint.txt

[russellb]

and I would change this to:

Suggested change

	run: sphinx-lint docs
	run: tools/sphinx-lint.sh

This ensures that we use the same arguments to the tool for both CI and local usage.

[russellb]

In other words, it's quicker to find issues using this during the dev (writing) phase than doing full doc builds? I'd agree with that. To make that a little easier, I'd include it in format.sh, as well. I have that in a branch if you want to cherry-pick it to your branch.

https://github.com/vllm-project/vllm/compare/main...russellb:vllm:rst-linting?expand=1

btw, I'm also happy to do the opposite - pull your commit into my branch and make the suggested updates. You will still get co-author credit either way. Just let me know how I can help!

[russellb]

thanks for the updates! one minor comment

[russellb]

any reason you have paths set for pushes but not PRs?

[rafvasq]

No reason, nice catch!

[rafvasq]

@russellb, thanks for the offer to help (and the reviews), I have to get my git practice in whenever I can 😅 I think I got this one right.

[russellb]

lgtm, thanks!

[DarkLight1337]

Thanks for improving the quality of docs!

[DarkLight1337]

Please merge from main to fix the test failures.