# SGLang Documentation

This is the documentation website for the SGLang project (https://github.com/sgl-project/sglang).

We recommend new contributors start from writing documentation, which helps you quickly understand SGLang codebase.
Most documentation files are located under the `docs/` folder.

## Docs Workflow

### Install Dependency

```bash
apt-get update && apt-get install -y pandoc parallel retry
pip install -r requirements.txt
```

### Update Documentation

Update your Jupyter notebooks in the appropriate subdirectories under `docs/`. If you add new files, remember to update `index.rst` (or relevant `.rst` files) accordingly.

- **`pre-commit run --all-files`** manually runs all configured checks, applying fixes if possible. If it fails the first time, re-run it to ensure lint errors are fully resolved. Make sure your code passes all checks **before** creating a Pull Request.

```bash
# 1) Compile all Jupyter notebooks
make compile  # This step can take a long time (10+ mins). You can consider skipping this step if you can make sure your added files are correct.
make html

# 2) Compile and Preview documentation locally with auto-build
# This will automatically rebuild docs when files change
# Open your browser at the displayed port to view the docs
bash serve.sh

# 2a) Alternative ways to serve documentation
# Directly use make serve
make serve
# With custom port
PORT=8080 make serve

# 3) Clean notebook outputs
# nbstripout removes notebook outputs so your PR stays clean
pip install nbstripout
find . -name '*.ipynb' -exec nbstripout {} \;

# 4) Pre-commit checks and create a PR
# After these checks pass, push your changes and open a PR on your branch
pre-commit run --all-files
```

## Documentation Style Guidelines

- For common functionalities, we prefer **Jupyter Notebooks** over Markdown so that all examples can be executed and validated by our docs CI pipeline. For complex features (e.g., distributed serving), Markdown is preferred.
- Keep in mind the documentation execution time when writing interactive Jupyter notebooks. Each interactive notebook will be run and compiled against every commit to ensure they are runnable, so it is important to apply some tips to reduce the documentation compilation time:
  - Use small models (e.g., `qwen/qwen2.5-0.5b-instruct`) for most cases to reduce server launch time.
  - Reuse the launched server as much as possible to reduce server launch time.
- Do not use absolute links (e.g., `https://docs.sglang.io/get_started/install.html`). Always prefer relative links (e.g., `../get_started/install.md`).
- Follow the existing examples to learn how to launch a server, send a query and other common styles.

## Documentation Build, Deployment, and CI

The SGLang documentation pipeline is based on **Sphinx** and supports rendering Jupyter notebooks (`.ipynb`) into HTML/Markdown for web display. Detailed logits can be found in the [Makefile](./Makefile).

### Notebook Execution (`make compile`)

The `make compile` target is responsible for executing notebooks before rendering:

* Finds all `.ipynb` files under `docs/` (excluding `_build/`)
* Executes notebooks in parallel using GNU Parallel, with a relatively small `--mem-fraction-static`
* Wraps execution with `retry` to reduce flaky failures
* Executes notebooks via `jupyter nbconvert --execute --inplace`
* Records execution timing in `logs/timing.log`

This step ensures notebooks contain up-to-date outputs with each commit in the main branch before rendering.

### Web Rendering (`make html`)

After compilation, Sphinx builds the website:

* Reads Markdown, reStructuredText, and Jupyter notebooks
* Renders them into HTML pages
* Outputs the website into:

```
docs/_build/html/
```

This directory is the source for online documentation hosting.

### Markdown Export (`make markdown`)

To support downstream consumers, we add a **new Makefile target**:

```bash
make markdown
```

This target:

* Does **not modify** `make compile`
* Scans all `.ipynb` files (excluding `_build/`)
* Converts notebooks directly to Markdown using `jupyter nbconvert --to markdown`
* Writes Markdown artifacts into the existing build directory:

```
docs/_build/html/markdown/<relative-path>.md
```

Example:

```
docs/advanced_features/lora.ipynb
→ docs/_build/html/markdown/advanced_features/lora.md
```

### CI Execution

In our [CI](https://github.com/sgl-project/sglang/blob/main/.github/workflows/release-docs.yml), the documentation pipeline first gets all the executed results and renders HTML and Markdown by:

```bash
make compile    # execute notebooks (ensure outputs are up to date)
make html       # build website as usual
make markdown   # export markdown artifacts into _build/html/markdown
```

Then, the compiled results are forced pushed to [sgl-project.io](https://github.com/sgl-project/sgl-project.github.io) for rendering. In other words, sgl-project.io is push-only. All the changes of SGLang docs should be made directly in SGLang main repo, then push to the sgl-project.io.