d5253fd710
Co-authored-by: leo <yixingwang@YIXINGs-MacBook-Pro.local> Co-authored-by: Aryan Kumar <aryan5v@users.noreply.github.com>
114 lines
3.8 KiB
Markdown
114 lines
3.8 KiB
Markdown
# FastVideo Documentation
|
|
|
|
This directory contains the FastVideo documentation built with MkDocs.
|
|
|
|
## Build the docs locally
|
|
|
|
```bash
|
|
# Install docs dependencies
|
|
uv pip install -r requirements-mkdocs.txt
|
|
npm ci --prefix docs
|
|
|
|
# Build the browser API/validator bundle and generate cookbook catalogs
|
|
npm run build:catalog --prefix docs
|
|
|
|
# Serve docs with live reload (recommended for development)
|
|
mkdocs serve
|
|
|
|
# Or build static site
|
|
mkdocs build
|
|
```
|
|
|
|
Run these commands from the repository root with Node 22.13+ (22.x) or Node 24+. Catalog generation uses authored
|
|
YAML and Node dependencies; it does not import FastVideo or install model runtime
|
|
dependencies. `mkdocs build` and `mkdocs serve` use the generated files without
|
|
regenerating them. A small MkDocs hook checks required assets before and after
|
|
the build and explains how to prepare them if missing. Rerun `build:catalog`
|
|
after changing cookbook sources. The npm `prebuild:catalog` and `pretest:cookbook`
|
|
hooks automatically run `build:assets`, including in CI. The combined
|
|
`docs/assets/cookbook-config/cookbook-config.js`, its
|
|
`cookbook-config.LICENSE.txt`, index and catalogs are Git-ignored and published
|
|
together; do not hand-edit or commit them. Handwritten modules live in `docs/js/`
|
|
and tests in `docs/tests/`.
|
|
|
|
## View the docs
|
|
|
|
### Development server (with live reload)
|
|
|
|
```bash
|
|
mkdocs serve
|
|
```
|
|
|
|
Then open your browser to: http://127.0.0.1:8000
|
|
|
|
### Static build
|
|
|
|
```bash
|
|
mkdocs build
|
|
python -m http.server -d site/
|
|
```
|
|
|
|
Then open your browser to: http://localhost:8000
|
|
|
|
## Automatic Deployment
|
|
|
|
Documentation is automatically built and deployed to GitHub Pages when relevant
|
|
changes are pushed to the `main` branch via `.github/workflows/infra-docs.yml`.
|
|
Pull requests run the build without deploying. The normal docs job installs
|
|
`requirements-mkdocs.txt` and the Node dependencies with `npm ci --prefix docs`,
|
|
runs scoped lint/format checks, cookbook tests and asset-check tests, generates catalogs with `npm run build:catalog --prefix docs`,
|
|
and runs `mkdocs build`. Invalid authored
|
|
metadata stops the build. The generated JSON remains Git-ignored but is copied
|
|
to `site/assets/cookbook-config/` for publication. The source-only
|
|
`docs/cookbook/options.yaml` and recipe manifests are excluded from the site.
|
|
No separate metadata job or runtime server is required.
|
|
|
|
## Update documentation dependencies
|
|
|
|
Edit `requirements-mkdocs.in`, then regenerate the pinned Linux/Python 3.12 lock file:
|
|
|
|
```bash
|
|
uv pip compile requirements-mkdocs.in \
|
|
-o requirements-mkdocs.txt \
|
|
--python-platform x86_64-manylinux_2_28 \
|
|
--python-version 3.12
|
|
```
|
|
|
|
## Local cookbook catalogs
|
|
|
|
Generate catalogs from the repository root:
|
|
|
|
```bash
|
|
npm ci --prefix docs
|
|
npm run build:catalog --prefix docs
|
|
```
|
|
|
|
This command builds the combined API/validator bundle first. Rerun it whenever
|
|
shared options, recipe manifests or baseline YAML change. Then `mkdocs build`
|
|
or `mkdocs serve` includes the generated assets. Generation loads no model
|
|
weights and performs no inference.
|
|
|
|
Inspect a deployment without a browser UI:
|
|
|
|
```bash
|
|
node docs/js/build-cookbook-config.mjs --preview fastwan21/cuda-rest
|
|
```
|
|
|
|
See [the contributor guide](contributing/cookbook_configuration.md) for recipe
|
|
authoring and local test commands, and [the API contract](cookbook/design.md)
|
|
for using the same catalogs from a cookbook UI.
|
|
|
|
## Check cookbook changes
|
|
|
|
```bash
|
|
npm run test:cookbook --prefix docs
|
|
npm run check:cookbook --prefix docs
|
|
python -m unittest discover -s docs/tests -p 'test_*.py'
|
|
```
|
|
|
|
`npm run format:cookbook --prefix docs` formats handwritten cookbook modules,
|
|
build scripts, tooling configuration and Node tests under `docs/`. The check
|
|
commands do not change files. The Node tests use synthetic fixtures for reusable
|
|
behavior and discover every production recipe for integration checks. They do
|
|
not launch serving processes.
|