Skip to content

Documentation Build Guide

This directory contains the source files for the vLLM-Omni documentation.

Building Documentation Locally

Prerequisites

Install documentation dependencies:

uv pip install -e ".[docs]"

Build and Serve Documentation

From the project root:

# 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

When using mkdocs serve, the documentation will be automatically available at http://127.0.0.1:8000. The server will automatically reload when you make changes to the documentation files.

Auto-generating API Documentation

The documentation automatically extracts docstrings from the code using mkdocstrings. To ensure your code is documented:

  1. Add docstrings to all public classes, functions, and methods
  2. Use Google or NumPy style docstrings (both are supported)
  3. Rebuild the documentation to see changes

Example 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")
    """

Documentation Structure

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

Naming Model Examples

Offline inference and online serving examples for the same model use the same directory name and the shared display name in examples/model_display_names.yml. Use these title forms:

  • # <Model>: Offline inference
  • # <Model>: Online serving

The documentation generator uses the full title for the page H1 and the shared display name alone for navigation, and fails the build if a mapped README uses a different H1. Keep checkpoint identifiers in commands and prose rather than in the display name, and do not rename an existing example directory solely to adjust its title because the directory defines its public documentation URL.

Publishing Documentation

The documentation is automatically deployed to GitHub Pages using GitHub Actions.

  1. Enable GitHub Pages:
  2. Go to repository Settings → Pages
  3. Set Source to GitHub Actions

  4. Save settings

  5. Push changes: 

    git push origin main

  6. Documentation will be available at:

  7. https://vllm-omni.readthedocs.io

The GitHub Actions workflow (.github/workflows/docs.yml) will automatically: - Build the documentation when you push to main branch - Deploy it to GitHub Pages - Update the documentation whenever you make changes

Read the Docs (Alternative)

You can also use Read the Docs for hosting:

  1. Sign up at https://readthedocs.org/
  2. Import the vllm-project/vllm-omni repository
  3. Read the Docs will automatically build using .readthedocs.yml
  4. Documentation will be available at: https://vllm-omni.readthedocs.io/

Configuration

The documentation configuration is in mkdocs.yml at the project root.

Tips

  • API Documentation: API docs are automatically generated using mkdocs-api-autonav and mkdocstrings
  • No need to manually create API pages - they're generated automatically
  • Use [module.name.ClassName][] syntax for cross-references in Summary pages
  • Code Snippets: Use --8<-- "path/to/file.py" for including code snippets
  • Markdown: Use Markdown for all documentation (no need for RST)
  • Material Theme: Use Material theme features like:
  • Admonitions: !!! note, !!! warning, etc.
  • Code blocks with syntax highlighting
  • Tabs for organizing content
  • Math formulas using pymdownx.arithmatex

Troubleshooting

Documentation not updating

  • Make sure you've saved all files
  • If using mkdocs serve, it should auto-reload
  • Check for syntax errors in mkdocs.yml
  • Ensure class names match exactly (case-sensitive)
  • Check that the module is imported correctly
  • Run mkdocs build --strict to check for errors

Build errors

  • Check Python version (requires 3.9+)
  • Ensure all dependencies are installed: pip install -e ".[docs]"
  • Check mkdocs.yml syntax with mkdocs build --strict