wehub-resource-sync
140 lines
4.0 KiB
Markdown
140 lines
4.0 KiB
Markdown
# Documentation Build Guide
|
|
|
|
This directory contains the source files for the vLLM-Omni documentation.
|
|
|
|
## Building Documentation Locally
|
|
|
|
### Prerequisites
|
|
|
|
Install documentation dependencies:
|
|
|
|
```bash
|
|
uv pip install -e ".[docs]"
|
|
```
|
|
|
|
### Build and Serve Documentation
|
|
|
|
From the project root:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```python
|
|
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
|
|
```
|
|
|
|
## Publishing Documentation
|
|
|
|
### GitHub Pages (Recommended)
|
|
|
|
The documentation is automatically deployed to GitHub Pages using GitHub Actions.
|
|
|
|
1. **Enable GitHub Pages**:
|
|
- Go to repository `Settings` → `Pages`
|
|
- Set `Source` to `GitHub Actions`
|
|
- Save settings
|
|
|
|
2. **Push changes**:
|
|
```bash
|
|
git push origin main
|
|
```
|
|
|
|
3. **Documentation will be available at**:
|
|
- `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`
|
|
|
|
### API links not working
|
|
|
|
- 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`
|