82 lines
3.4 KiB
Markdown
82 lines
3.4 KiB
Markdown
# Documenting FastVideo
|
|
|
|
FastVideo documentation is built with Blume and published at
|
|
[haoailab.com/FastVideo](https://haoailab.com/FastVideo/).
|
|
|
|
## Source ownership
|
|
|
|
- Edit guides under `docs/`. Keep runnable examples under `examples/` and `scripts/`.
|
|
- Edit the welcome page, Fast Models catalog, and cookbook model pages under
|
|
`docs-site/content/`, `docs-site/islands/`, and `docs-site/lib/`.
|
|
- Edit sidebar labels and grouping in `docs-site/navigation.json`. Group by reader
|
|
task. Hardware, integrations, and model-specific guides belong under Run inference.
|
|
- Python reference pages are extracted from source with Griffe. They require no
|
|
FastVideo installation, GPU packages, or model imports.
|
|
- Do not edit `.generated/`, `public/`, or `dist/`. Preparation recreates them.
|
|
|
|
## Write a task guide
|
|
|
|
Give each page one task and one audience. Use this order where it applies:
|
|
|
|
1. Explain what the reader will do and when to use the guide.
|
|
2. List prerequisites, supported runtimes, and hardware assumptions.
|
|
3. Provide the shortest runnable example and its expected output.
|
|
4. Explain configuration choices after the working example.
|
|
5. Put troubleshooting beside the relevant command or in a short closing section.
|
|
6. Link to the next task and the relevant reference.
|
|
|
|
Keep measured results, hardware and limitations together. Put implementation
|
|
history and rejected experiments in an architecture or research page, rather
|
|
than between setup commands. Link to installation instead of repeating it.
|
|
The main quick start owns the first generation example; specialized guides
|
|
build on it. Keep model IDs in the catalog and runnable sources consistent.
|
|
|
|
## Build and check
|
|
|
|
From the repository root, use Node 24 and Python 3.12:
|
|
|
|
```bash
|
|
uv venv docs-site/.venv --python 3.12
|
|
uv pip install --python docs-site/.venv/bin/python -r requirements-docs.txt
|
|
npm ci --prefix docs
|
|
npm ci --prefix docs-site
|
|
npm run dev --prefix docs-site
|
|
```
|
|
|
|
Open the printed URL under `/FastVideo`. After editing canonical guides, rerun
|
|
`npm run prepare:content --prefix docs-site` and restart the dev server.
|
|
For a static production build:
|
|
|
|
```bash
|
|
npm run check --prefix docs-site
|
|
npm run format:check --prefix docs-site
|
|
npm run build --prefix docs-site
|
|
npm run validate --prefix docs-site
|
|
npm run test:content --prefix docs-site
|
|
npm test --prefix docs-site
|
|
```
|
|
|
|
Use `DOCS_PYTHON=/path/to/python` to select another documentation environment.
|
|
Install Chromium with `npm exec --prefix docs-site -- playwright install chromium`
|
|
if the browser suite requests it. Python renderer tests run with
|
|
`docs-site/.venv/bin/python -m unittest discover -s docs-site/tests -p 'test_*.py'`.
|
|
|
|
## Publish
|
|
|
|
The existing `.github/workflows/infra-docs.yml` builds Blume, checks content and
|
|
browser interactions, and uploads `docs-site/dist/` to GitHub Pages. Only pushes
|
|
to `main` deploy. The custom domain, GitHub Pages environment, and `/FastVideo`
|
|
base path remain the same. Pull requests validate the build without deploying.
|
|
|
|
When changing dependencies, edit `requirements-docs.in` and regenerate its lock:
|
|
|
|
```bash
|
|
uv pip compile requirements-docs.in -o requirements-docs.txt \
|
|
--python-platform x86_64-manylinux_2_28 --python-version 3.12
|
|
```
|
|
|
|
The committed migration anchor manifest records the previous site's URLs and
|
|
fragments. It is a compatibility contract, not generated content to refresh on
|
|
each build. A deliberate URL change needs a redirect and an updated regression
|
|
check before removing an old route.
|