文档构建指南¶

此目录包含 vLLM-Omni 文档的源文件。

构建文档本地¶

先决条件¶

安装文档依赖项

uv pip install -e ".[docs]"

构建和提供文档¶

从项目根目录

# Serve documentation locally (auto-reload on changes)
# This starts a local web server at http://127.0.0.1:8000
mkdocs serve

# Build static site (generates HTML files in site/ directory)
mkdocs build

使用 mkdocs serve 时，文档将自动在 http://127.0.0.1:8000 可用。当您更改文档文件时，服务器将自动重新加载。

自动生成 API 文档¶

文档使用 mkdocstrings 自动提取代码中的 docstrings。为确保您的代码有文档说明

为所有公共类、函数和方法添加 docstrings
使用 Google 或 NumPy 风格的 docstrings (两者都支持)
重新构建文档以查看更改

示例 docstring

class Omni:
    """Main entry point for vLLM-Omni inference.

    This class provides a high-level interface for running multi-modal
    inference with non-autoregressive models.

    Args:
        model: Model name or path
        stage_configs: Optional stage configurations
        **kwargs: Additional arguments passed to the engine

    Example:
        >>> llm = Omni(model="Qwen/Qwen2.5-Omni")
        >>> outputs = llm.generate(prompts="Hello")
    """

文档结构¶

docs/
├── index.md              # Main documentation page
├── getting_started/      # Getting started guides
├── architecture/        # Architecture documentation
├── api/                 # API reference (auto-generated from code)
├── examples/            # Code examples
└── stylesheets/         # Custom CSS

发布文档¶

GitHub Pages (推荐)¶

文档通过 GitHub Actions 自动部署到 GitHub Pages。

启用 GitHub Pages:
转到仓库 Settings → Pages
将 Source 设置为 GitHub Actions
保存设置
推送更改:
```
git push origin main
```
文档将可在以下网址找到：:
https://vllm-omni.readthedocs.io

GitHub Actions 工作流 (.github/workflows/docs.yml) 将自动执行以下操作： - 当您推送到 main 分支时构建文档 - 将其部署到 GitHub Pages - 在您进行更改时更新文档

Read the Docs (替代方案)¶

您也可以使用 Read the Docs 进行托管

在 https://readthedocs.org/ 注册
导入 vllm-project/vllm-omni 仓库
Read the Docs 将使用 .readthedocs.yml 自动构建
文档将可在以下网址找到： https://vllm-omni.readthedocs.io/

配置¶

文档配置位于项目根目录的 mkdocs.yml 文件中。

提示¶

API 文档: API 文档使用 mkdocs-api-autonav 和 mkdocstrings 自动生成
无需手动创建 API 页面 - 它们会自动生成
在摘要页面中使用 [module.name.ClassName][] 语法进行交叉引用
代码片段: 使用 --8<-- "path/to/file.py" 来包含代码片段
Markdown: 对所有文档使用 Markdown (无需 RST)
Material 主题: 使用 Material 主题的特性，例如
Admonitions: !!! note, !!! warning, 等。
带有语法高亮的代码块
用于组织内容的选项卡
使用 pymdownx.arithmatex 的数学公式

故障排除¶

文档未更新¶

确保您已保存所有文件
如果使用 mkdocs serve，它应该会自动重新加载
检查 mkdocs.yml 中的语法错误

API 链接不工作¶

确保类名完全匹配 (区分大小写)
检查模块是否已正确导入
运行 mkdocs build --strict 来检查错误

构建错误¶

检查 Python 版本 (需要 3.9+)
确保所有依赖项都已安装: pip install -e ".[docs]"
使用 mkdocs build --strict 检查 mkdocs.yml 语法