Skip to content

Add full API docs and improve the UX of navigating them #17485

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.

Sign up for GitHub

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

Jump to bottom
Merged
merged 64 commits into from
May 4, 2025
Merged

Add full API docs and improve the UX of navigating them #17485

merged 64 commits into from
May 4, 2025

Conversation

@hmellor
Copy link
Member

@hmellor hmellor commented Apr 30, 2025 •
edited by github-actions bot
Loading

Changes:

  • Ported from sphinx.ext.autodoc and sphinx.ext.autosummary to autodoc2:
    • autodoc2 supports myst (markdown) so we can stop writing rst formatted docstrings
    • The entire codebase is documented in API Reference
    • All of these docs can be cross-referenced throughout the docs
  • Updated the API Reference index to include all the important classes/functions we already singled out on the individual pages we had before (reduces users having to click around and shows a more global picture of the APIs we expect them to be using)
  • autodoc2 statically analyses the code so:
    • No more mocked import issues outside of docs/
    • Greatly reduced requirements/docs.txt
    • RTD builds are slower because this analysis takes time
  • sphinx.ext.linkcode no longer requires vllm to be importable

This should help JSON CLI args document themselves (such as in #17420)

hmellor added 3 commits April 30, 2025 17:36
@hmellor
Add config page to index
0109731 
Signed-off-by: Harry Mellor <19981378+hmellor@users.noreply.github.com>
@hmellor
Configure autodoc2
61d0b07 
Signed-off-by: Harry Mellor <19981378+hmellor@users.noreply.github.com>
@hmellor
Add config.md
3eaf926 
Signed-off-by: Harry Mellor <19981378+hmellor@users.noreply.github.com>
@github-actions
Copy link

👋 Hi! Thank you for contributing to the vLLM project.

💬 Join our developer Slack at https://slack.vllm.ai to discuss your PR in #pr-reviews, coordinate on features in #feat- channels, or join special interest groups in #sig- channels.

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 either: Add ready label to the PR or enable auto-merge.

🚀

@hmellor hmellor changed the title Add-config-docs Add config classes to API docs Apr 30, 2025
@mergify mergify bot added the documentation Improvements or additions to documentation label Apr 30, 2025
@hmellor
Add missing requirement
9e5fad8 
Signed-off-by: Harry Mellor <19981378+hmellor@users.noreply.github.com>
@mergify mergify bot added the ci/build label Apr 30, 2025
@hmellor hmellor mentioned this pull request Apr 30, 2025
Closed
DarkLight1337
DarkLight1337 reviewed Apr 30, 2025
View reviewed changes
hmellor added 2 commits April 30, 2025 18:57
@hmellor
Typo
57f40c5 
Signed-off-by: Harry Mellor <19981378+hmellor@users.noreply.github.com>
@hmellor
Replace links for offline
ef6a592 
Signed-off-by: Harry Mellor <19981378+hmellor@users.noreply.github.com>
@aarnphm aarnphm requested a review from DarkLight1337 April 30, 2025 20:28
@hmellor
Copy link
Member Author

hmellor commented Apr 30, 2025 •
edited
Loading

I almost have a patch that replaces autodoc and handles API documentation much better in general.

Let's hold off on merging this until that is ready

hmellor added 9 commits May 1, 2025 10:25
@hmellor
Generate full API docs
7964a17 
Signed-off-by: Harry Mellor <19981378+hmellor@users.noreply.github.com>
@hmellor
Replace tiny API ref files with one index of all important stuff
a16ebb0 
Signed-off-by: Harry Mellor <19981378+hmellor@users.noreply.github.com>
@hmellor
Fix some links
3283441 
Signed-off-by: Harry Mellor <19981378+hmellor@users.noreply.github.com>
@hmellor
Fix some sphinx errors
ede54dc 
Signed-off-by: Harry Mellor <19981378+hmellor@users.noreply.github.com>
@hmellor
Remove old autodoc and autosummary
c2d2cdb 
Signed-off-by: Harry Mellor <19981378+hmellor@users.noreply.github.com>
@hmellor
linkcode_resolve without importing vllm
7974d65 
Signed-off-by: Harry Mellor <19981378+hmellor@users.noreply.github.com>
@hmellor
Improve navigation of API docs
e473010 
Signed-off-by: Harry Mellor <19981378+hmellor@users.noreply.github.com>
@hmellor
Don't include undocumented or private objects
cb5c57c 
Signed-off-by: Harry Mellor <19981378+hmellor@users.noreply.github.com>
@hmellor
Exclude auto generated files we don't use
e4dd76f 
Signed-off-by: Harry Mellor <19981378+hmellor@users.noreply.github.com>
@hmellor hmellor changed the title Add config classes to API docs Add full API docs and improve the UX of navigating them May 1, 2025
@hmellor
Merge branch 'main' into add-config-docs
92f738c 
Signed-off-by: Harry Mellor <19981378+hmellor@users.noreply.github.com>
@mergify mergify bot removed the needs-rebase label May 2, 2025
hmellor added 3 commits May 2, 2025 21:58
@hmellor
pre-commit
0dfe026 
Signed-off-by: Harry Mellor <19981378+hmellor@users.noreply.github.com>
@hmellor
pre-commit
5bbc79b 
Signed-off-by: Harry Mellor <19981378+hmellor@users.noreply.github.com>
@hmellor
Revert change to platforms/__init__.py (we're not documenting that yet)
144d4e4 
Signed-off-by: Harry Mellor <19981378+hmellor@users.noreply.github.com>
@DarkLight1337
Copy link
Member

Hmm it's still a bit difficult to navigate to the API docs of specific modules. Can we make Offline Inference, vLLM Engines etc. sub-pages under Summary, and similar for the "vllm" auto-generated pages?

@hmellor
Copy link
Member Author

hmellor commented May 3, 2025

Ok, currently working on improving the left sidebar so that the entire API can be navigated properly

hmellor added 11 commits May 3, 2025 10:29
@hmellor
Don't ignore any generated API docs
5893358 
Signed-off-by: Harry Mellor <19981378+hmellor@users.noreply.github.com>
@hmellor
Auto document the full API, not just __all__
a6d559e 
Signed-off-by: Harry Mellor <19981378+hmellor@users.noreply.github.com>
@hmellor
Sort alphabetically for ease of navigation
c86c2f3 
Signed-off-by: Harry Mellor <19981378+hmellor@users.noreply.github.com>
@hmellor
Improve AsyncLLM docstring
c912d93 
Signed-off-by: Harry Mellor <19981378+hmellor@users.noreply.github.com>
@hmellor
Improve LLMEngine docstirng
09191c6 
Signed-off-by: Harry Mellor <19981378+hmellor@users.noreply.github.com>
@hmellor
Don't skip undocumented objects
4bec536 
Signed-off-by: Harry Mellor <19981378+hmellor@users.noreply.github.com>
@hmellor
Use code block for ASCII diagram
aa8102b 
Signed-off-by: Harry Mellor <19981378+hmellor@users.noreply.github.com>
@hmellor
Dis ambiguous references in docstrings
56bc677 
Signed-off-by: Harry Mellor <19981378+hmellor@users.noreply.github.com>
@hmellor
Remove unnecessary newline
61bf9da 
Signed-off-by: Harry Mellor <19981378+hmellor@users.noreply.github.com>
@hmellor
pre-commit
09490fd 
Signed-off-by: Harry Mellor <19981378+hmellor@users.noreply.github.com>
@hmellor
Make build leaner
f8f3474 
Signed-off-by: Harry Mellor <19981378+hmellor@users.noreply.github.com>
DarkLight1337
DarkLight1337 approved these changes May 3, 2025
View reviewed changes
Copy link
Member

@DarkLight1337 DarkLight1337 left a comment

Choose a reason for hiding this comment

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

This looks good now. Thanks for improving the dev experience!

@DarkLight1337
Copy link
Member

To avoid breaking stuff, let's wait for #17607 to unblock CI

@DarkLight1337 DarkLight1337 added the ready ONLY add when PR is ready to merge/full CI is needed label May 3, 2025
hmellor added 3 commits May 3, 2025 18:01
@hmellor
Fix buildkite docs build test
bda4378 
Signed-off-by: Harry Mellor <19981378+hmellor@users.noreply.github.com>
@hmellor
Merge branch 'main' into add-config-docs
7df399f
@hmellor
Fix import error in example
a0d7039 
Signed-off-by: Harry Mellor <19981378+hmellor@users.noreply.github.com>
@vllm-bot vllm-bot merged commit d6484ef into vllm-project:main May 4, 2025
77 of 80 checks passed
@hmellor hmellor deleted the add-config-docs branch May 4, 2025 08:06
RichardoMrMu pushed a commit to RichardoMrMu/vllm that referenced this pull request May 12, 2025
@hmellor
Add full API docs and improve the UX of navigating them (vllm-project…
9ada3f6 
…#17485)

Signed-off-by: Harry Mellor <19981378+hmellor@users.noreply.github.com>
Signed-off-by: Mu Huai <tianbowen.tbw@antgroup.com>
mawong-amd pushed a commit to ROCm/vllm that referenced this pull request May 14, 2025
@hmellor @mawong-amd
Add full API docs and improve the UX of navigating them (vllm-project…
86c86c6 
…#17485)

Signed-off-by: Harry Mellor <19981378+hmellor@users.noreply.github.com>
zzzyq pushed a commit to zzzyq/vllm that referenced this pull request May 24, 2025
@hmellor
Add full API docs and improve the UX of navigating them (vllm-project…
27eb35f 
…#17485)

Signed-off-by: Harry Mellor <19981378+hmellor@users.noreply.github.com>
Signed-off-by: Yuqi Zhang <yuqizhang@google.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@DarkLight1337 DarkLight1337 DarkLight1337 approved these changes

@WoosukKwon WoosukKwon Awaiting requested review from WoosukKwon WoosukKwon is a code owner

@robertgshaw2-redhat robertgshaw2-redhat Awaiting requested review from robertgshaw2-redhat robertgshaw2-redhat is a code owner

@njhill njhill Awaiting requested review from njhill njhill is a code owner

@ywang96 ywang96 Awaiting requested review from ywang96 ywang96 is a code owner

@comaniac comaniac Awaiting requested review from comaniac comaniac is a code owner

@alexm-redhat alexm-redhat Awaiting requested review from alexm-redhat alexm-redhat is a code owner

@zhuohan123 zhuohan123 Awaiting requested review from zhuohan123 zhuohan123 is a code owner

@youkaichao youkaichao Awaiting requested review from youkaichao youkaichao is a code owner

Assignees

No one assigned

Labels

ci/build documentation Improvements or additions to documentation frontend multi-modality Related to multi-modality (#4194) ready ONLY add when PR is ready to merge/full CI is needed speculative-decoding v1

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@hmellor @DarkLight1337 @vllm-bot