[Docs]: Fix errors and warnings about griffe spotted by `mkdocs build`

[windsonsea]

When a document is modified, the CI process may generate many warnings after running the command:

python -m mkdocs build --clean --site-dir $READTHEDOCS_OUTPUT/html --config-file mkdocs.yaml

This issue serves as a tracker to monitor and manage the progress of resolving those warnings:

vllm/attention/ops/ - 6 warnings

• WARNING - griffe: vllm/attention/ops/common.py:20: No type or annotation for parameter 'output'
• WARNING - griffe: vllm/attention/ops/common.py:20: Parameter 'output' does not appear in the function signature
• WARNING - griffe: vllm/attention/ops/common.py:21: No type or annotation for parameter 'lses '
• WARNING - griffe: vllm/attention/ops/common.py:21: Parameter 'lses ' does not appear in the function signature
• WARNING - griffe: vllm/attention/ops/common.py:91: No type or annotation for parameter 'output'
• WARNING - griffe: vllm/attention/ops/common.py:91: Parameter 'output' does not appear in the function signature
• WARNING - griffe: vllm/attention/ops/common.py:92: No type or annotation for parameter 'lses '
• WARNING - griffe: vllm/attention/ops/common.py:92: Parameter 'lses ' does not appear in the function signature
• WARNING - griffe: vllm/attention/ops/common.py:22: Failed to get 'name: description' pair from 'cp, batch, q_heads, v_head_dim'

@samzong (DONE) vllm/benchmarks/ - 6 warnings

• WARNING - griffe: vllm/benchmarks/lib/ready_checker.py:24: No type or annotation for parameter 'request_func'
• WARNING - griffe: vllm/benchmarks/serve.py:141: Confusing indentation for continuation line 17 in docstring, should be 4 * 2 = 8 spaces, not 5
• WARNING - griffe: vllm/benchmarks/datasets.py:105: Failed to get 'name: description' pair from 'indicates that a default or random dataset might be used.'
• WARNING - griffe: vllm/benchmarks/datasets.py:107: Failed to get 'name: description' pair from 'sampling. Defaults to DEFAULT_SEED.'
• WARNING - griffe: vllm/benchmarks/datasets.py:237: Failed to get 'name: description' pair from 'request_id_prefix (str) The prefix of the request ids.'
• WARNING - griffe: vllm/benchmarks/datasets.py:213: Failed to get 'name: description' pair from 'request_id_prefix (str) The prefix of request_id.'
• WARNING - mkdocs_autorefs: api/vllm/benchmarks/datasets.md: from /home/docs/checkouts/readthedocs.org/user_builds/vllm/checkouts/24820/vllm/benchmarks/datasets.py:161: (vllm.benchmarks.datasets.BenchmarkDataset.get_random_lora_request) Could not find cross-reference target 'LoRARequest'

@Zerohertz (DONE) vllm/compilation/ and vllm/engine/ - 4 warnings

• WARNING - griffe: vllm/compilation/base_static_graph.py:43: No type or annotation for parameter '*args'
• WARNING - griffe: vllm/compilation/base_static_graph.py:45: No type or annotation for parameter '**kwargs'
• WARNING - griffe: vllm/engine/multiprocessing/engine.py:73: No type or annotation for parameter '*args'
• WARNING - griffe: vllm/engine/multiprocessing/engine.py:74: No type or annotation for parameter '**kwargs'
• ERROR - griffe: vllm/engine/async_timeout.py:19: Failed to get annotation expression from Subscript: AliasResolutionError: Could not resolve alias vllm.engine.async_timeout.asyncio_timeout pointing at asyncio.timeout (in vllm/engine/async_timeout.py:16)
• WARNING - mkdocs_autorefs: api/vllm/engine/output_processor/util.md: from /home/docs/checkouts/readthedocs.org/user_builds/vllm/checkouts/24820/vllm/engine/output_processor/util.py:15: (vllm.engine.output_processor.util.create_output_by_sequence_group) Could not find cross-reference target 'sequence group'
• WARNING - mkdocs_autorefs: api/vllm/engine/output_processor/util.md: from /home/docs/checkouts/readthedocs.org/user_builds/vllm/checkouts/24820/vllm/engine/output_processor/util.py:15: (vllm.engine.output_processor.util.create_output_by_sequence_group) Could not find cross-reference target 'step'

@Zerohertz vllm/distributed/device_communicators/ - 5 warnings

• WARNING - griffe: vllm/distributed/device_communicators/shm_object_storage.py:255: Failed to get 'name: description' pair from 'frees the maximum size of the ring buffer.'
• WARNING - mkdocs_autorefs: api/vllm/distributed/device_communicators/shm_object_storage.md: from /home/docs/checkouts/readthedocs.org/user_builds/vllm/checkouts/24820/vllm/distributed/device_communicators/shm_object_storage.py:387: (vllm.distributed.device_communicators.shm_object_storage.SingleWriterShmObjectStorage) Could not find cross-reference target 'metadata_size'
• WARNING - mkdocs_autorefs: api/vllm/distributed/device_communicators/shm_object_storage.md: from /home/docs/checkouts/readthedocs.org/user_builds/vllm/checkouts/24820/vllm/distributed/device_communicators/shm_object_storage.py:23: (vllm.distributed.device_communicators.shm_object_storage.SingleWriterShmRingBuffer) Could not find cross-reference target '4-byte size'
• WARNING - mkdocs_autorefs: api/vllm/distributed/device_communicators/shm_object_storage.md: from /home/docs/checkouts/readthedocs.org/user_builds/vllm/checkouts/24820/vllm/distributed/device_communicators/shm_object_storage.py:23: (vllm.distributed.device_communicators.shm_object_storage.SingleWriterShmRingBuffer) Could not find cross-reference target '4-byte chunk_size'
• WARNING - mkdocs_autorefs: api/vllm/distributed/device_communicators/shm_object_storage.md: from /home/docs/checkouts/readthedocs.org/user_builds/vllm/checkouts/24820/vllm/distributed/device_communicators/shm_object_storage.py:185: (vllm.distributed.device_communicators.shm_object_storage.SingleWriterShmRingBuffer.allocate_buf) Could not find cross-reference target '4-byte size'

@Zerohertz vllm/entrypoints/openai/ - 2 warnings

• WARNING - mkdocs_autorefs: api/vllm/entrypoints/openai/serving_engine.md: from /home/docs/checkouts/readthedocs.org/user_builds/vllm/checkouts/24820/vllm/entrypoints/openai/serving_engine.py:699: (vllm.entrypoints.openai.serving_engine.OpenAIServing._tokenize_prompt_input_async) Could not find cross-reference target 'vllm.entrypoints.openai.serving_engine.OpenAIServing._tokenize_prompt_input_or_inputs'
• WARNING - mkdocs_autorefs: api/vllm/entrypoints/openai/serving_engine.md: from /home/docs/checkouts/readthedocs.org/user_builds/vllm/checkouts/24820/vllm/entrypoints/openai/serving_engine.py:720: (vllm.entrypoints.openai.serving_engine.OpenAIServing._tokenize_prompt_inputs_async) Could not find cross-reference target 'vllm.entrypoints.openai.serving_engine.OpenAIServing._tokenize_prompt_input_or_inputs'

@windsonsea (DONE) vllm/lora/ops/ - 4 warnings

• WARNING - griffe: vllm/lora/ops/triton_ops/lora_kernel_metadata.py:138: Failed to get 'name: description' pair from 'pass.'
• WARNING - griffe: vllm/lora/ops/triton_ops/lora_kernel_metadata.py:86: Failed to get 'name: description' pair from 'for each input token.'
• WARNING - griffe: vllm/lora/ops/triton_ops/lora_kernel_metadata.py:85: Parameter 'token_lora_tensor' does not appear in the function signature
• WARNING - griffe: vllm/lora/ops/xla_ops/lora_ops.py:95: Parameter 'output_tensor' does not appear in the function signature

@samzong (DONE) vllm/model_executor/layers/mamba/ops/ and vllm/model_executor/models/ - 6 warnings

• WARNING - mkdocs_autorefs: api/vllm/model_executor/layers/mamba/ops/causal_conv1d.md: from /home/docs/checkouts/readthedocs.org/user_builds/vllm/checkouts/24820/vllm/model_executor/layers/mamba/ops/causal_conv1d.py:857: (vllm.model_executor.layers.mamba.ops.causal_conv1d.causal_conv1d_update) Could not find cross-reference target 'shape=3: single or multiple tokens prediction'
• WARNING - mkdocs_autorefs: api/vllm/model_executor/models/blip2.md: from /home/docs/checkouts/readthedocs.org/user_builds/vllm/checkouts/24820/vllm/model_executor/models/blip2.py:656: (vllm.model_executor.models.blip2.Blip2ForConditionalGeneration.forward) Could not find cross-reference target 'Blip2ImageInputs'
• WARNING - mkdocs_autorefs: api/vllm/model_executor/models/llava.md: from /home/docs/checkouts/readthedocs.org/user_builds/vllm/checkouts/24820/vllm/model_executor/models/llava.py:705: (vllm.model_executor.models.llava.LlavaForConditionalGeneration.forward) Could not find cross-reference target 'LlavaImageInputs'
• WARNING - mkdocs_autorefs: api/vllm/model_executor/models/llava_next.md: from /home/docs/checkouts/readthedocs.org/user_builds/vllm/checkouts/24820/vllm/model_executor/models/llava_next.py:500: (vllm.model_executor.models.llava_next.LlavaNextForConditionalGeneration.forward) Could not find cross-reference target 'get_llava_next_image_feature_size'
• WARNING - mkdocs_autorefs: api/vllm/model_executor/models/llava_next.md: from /home/docs/checkouts/readthedocs.org/user_builds/vllm/checkouts/24820/vllm/model_executor/models/llava_next.py:500: (vllm.model_executor.models.llava_next.LlavaNextForConditionalGeneration.forward) Could not find cross-reference target 'LlavaNextImageInputs'
• WARNING - mkdocs_autorefs: api/vllm/model_executor/models/mistral3.md: from /home/docs/checkouts/readthedocs.org/user_builds/vllm/checkouts/24820/vllm/model_executor/models/mistral3.py:551: (vllm.model_executor.models.mistral3.Mistral3ForConditionalGeneration.forward) Could not find cross-reference target 'Mistral3ImagePixelInputs'

@windsonsea vllm/multimodal/ - 5 warnings

• WARNING - griffe: vllm/multimodal/inputs.py:571: No type or annotation for parameter 'slices'
• WARNING - griffe: vllm/multimodal/inputs.py:571: Parameter 'slices' does not appear in the function signature
• WARNING - griffe: vllm/multimodal/utils.py:398: No type or annotation for parameter 'mm_inputs'
• WARNING - griffe: vllm/multimodal/utils.py:398: Parameter 'mm_inputs' does not appear in the function signature
• WARNING - mkdocs_autorefs: api/vllm/multimodal/profiling.md: from /home/docs/checkouts/readthedocs.org/user_builds/vllm/checkouts/24820/vllm/multimodal/profiling.py:300: (vllm.multimodal.profiling.MultiModalProfiler.get_mm_max_contiguous_tokens) Could not find cross-reference target 'IMG'
• WARNING - mkdocs_autorefs: api/vllm/multimodal/profiling.md: from /home/docs/checkouts/readthedocs.org/user_builds/vllm/checkouts/24820/vllm/multimodal/profiling.py:300: (vllm.multimodal.profiling.MultiModalProfiler.get_mm_max_contiguous tokens) Could not find cross-reference target 'IMG'

@windsonsea (DONE) vllm/profiler/ and vllm/transformers_utils/ - 4 warnings

• WARNING - griffe: vllm/profiler/layerwise_profile.py:355: Failed to get 'name: description' pair from 'num_running_seqs will be passed to LayerProfileResults for metadata'
• WARNING - griffe: vllm/profiler/layerwise_profile.py:356: Failed to get 'name: description' pair from 'update. Defaults to None.'
• WARNING - griffe: vllm/transformers_utils/configs/jais.py:76: Failed to get 'name: description' pair from 'scale_attn_by_inverse_layer_idx'
• WARNING - mkdocs_autorefs: api/vllm/transformers_utils/dynamic_module.md: from /home/docs/checkouts/readthedocs.org/user_builds/vllm/checkouts/24820/vllm/transformers_utils/dynamic_module.py:29: (vllm.transformers_utils.dynamic_module.try_get_class_from_dynamic_module) Could not find cross-reference target 'transformers.dynamic_module_utils.get_class_from_dynamic_module'

@wwl2755 (DONE) vllm/utils/ and vllm/worker/ - 5 warnings

• WARNING - griffe: vllm/utils/init.py:3282: No type or annotation for parameter 'input'
• WARNING - griffe: vllm/utils/init.py:3297: No type or annotation for parameter 'input'
• WARNING - griffe: vllm/utils/init.py:3217: Confusing indentation for continuation line 5 in docstring, should be 4 * 2 = 8 spaces, not 6
• WARNING - griffe: vllm/worker/model_runner.py:1814: No type or annotation for parameter 'model_input'
• WARNING - griffe: vllm/worker/model_runner.py:1815: No type or annotation for parameter 'kv_caches'
• WARNING - griffe: vllm/worker/model_runner.py:1839: No type or annotation for parameter 'model_input'
• WARNING - griffe: vllm/worker/model_runner.py:1840: No type or annotation for parameter 'kv_caches'

@wwl2755 (DONE) vllm/v1/core/, vllm/v1/sample/, and vllm/v1/worker/ - 8 warnings

• WARNING - griffe: vllm/v1/sample/rejection_sampler.py:353: No type or annotation for parameter 'num_tokens '
• WARNING - griffe: vllm/v1/sample/rejection_sampler.py:353: Parameter 'num_tokens ' does not appear in the function signature
• WARNING - griffe: vllm/v1/sample/rejection_sampler.py:355: Parameter 'num_draft_tokens ' does not appear in the function signature
• WARNING - griffe: vllm/v1/sample/rejection_sampler.py:355: No type or annotation for parameter 'num_draft_tokens'
• WARNING - griffe: vllm/v1/sample/rejection_sampler.py:357: Parameter 'generators ' does not appear in the function signature
• WARNING - griffe: vllm/v1/sample/rejection_sampler.py:357: No type or annotation for parameter 'generators '
• WARNING - griffe: vllm/v1/sample/rejection_sampler.py:360: Parameter 'device ' does not appear in the function signature
• WARNING - griffe: vllm/v1/sample/rejection_sampler.py:360: No type or annotation for parameter 'device '
• WARNING - griffe: vllm/v1/worker/gpu_model_runner.py:1357: Confusing indentation for continuation line 5 in docstring, should be 4 * 2 = 8 spaces, not 6
• WARNING - mkdocs_autorefs: api/vllm/v1/core/kv_cache_manager.md: from /home/docs/checkouts/readthedocs.org/user_builds/vllm/checkouts/24820/vllm/v1/core/kv_cache_manager.py:26: (vllm.v1.core.kv_cache_manager.KVCacheBlocks.blocks) Could not find cross-reference target 'j'
• WARNING - mkdocs_autorefs: api/vllm/v1/worker/utils.md: from /home/docs/checkouts/readthedocs.org/user_builds/vllm/checkouts/24820/vllm/v1/worker/utils.py:196: (vllm.v1.worker.utils.gather_mm_placeholders) Could not find cross-reference target 'scatter_mm_placeholders'

@wwl2755 (DONE) Documentation and other warnings - 1 warning

• WARNING - Doc file 'api/vllm/multimodal/index.md' contains a link '../../../design/mm_processing.html', but the target 'design/mm_processing.html' is not found among documentation files. Did you mean '../../../design/mm_processing.md'?

Suggest a potential alternative/fix

• If a file have several warnings, please have a try to fix it in a single PR.
• Once the PR is merged, please check the proper box above.

Before submitting a new issue...

• Make sure you already searched for relevant issues, and asked the chatbot living at the bottom right corner of the documentation page, which can answer lots of frequently asked questions.

[windsonsea]

Also see Slack messages and instructions from owners:

📚 Call for help for anyone interested in helping with the docs

We'd like to add strict: true to mkdocs.yaml but there are currently too many warnings coming from the docstrings in the API Reference docs.

❓ How can you help?

Simply run:

uv venv
. .venv/bin/activate
uv pip install -r requirements/docs.txt
mkdocs build > docs.log 2>&1

Then go through docs.log and fix as many warnings as you can!

[punitvara]

I will also try to fix some warnings and send PR.

[wwl2755]

#25042 Fixed all warnings related to mkdocs_autorefs:cross-reference produced from mkdocs build

[hmellor]

Thank you everyone for the PRs so far!

So that we spend less money on CI for this effort, could future PRs please be a little larger? For example, 10-20 warnings solved.

[hmellor]

Also, for cross referencing warnings, please check out https://mkdocstrings.github.io/usage/#cross-references for the correct syntax