Unverified Commit b9b3b098 authored by samzong's avatar samzong Committed by GitHub
Browse files

feat: support docs auto live-reload with sphinx-autobuild (#4111)


Signed-off-by: default avatarsamzong <samzong.lu@gmail.com>
Co-authored-by: default avatarzhaochenyang20 <zhaochen20@outlook.com>
parent aee30630
# Minimal Makefile for Sphinx documentation
SPHINXOPTS ?=
SPHINXBUILD ?= sphinx-build
SPHINXAUTOBUILD ?= sphinx-autobuild
SOURCEDIR = .
BUILDDIR = _build
PORT ?= 8003
help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
@echo ""
@echo "Additional targets:"
@echo " serve to build and serve documentation with auto-build and live reload"
# Compile Notebook files and record execution time
compile:
......@@ -32,8 +37,15 @@ compile:
echo "Total execution time: $${TOTAL_ELAPSED}s" >> logs/timing.log; \
echo "All Notebook execution timings:" && cat logs/timing.log
# Serve documentation with auto-build and live reload
serve:
@echo "Starting auto-build server at http://localhost:$(PORT)"
@$(SPHINXAUTOBUILD) "$(SOURCEDIR)" "$(BUILDDIR)/html" \
--port $(PORT) \
--watch $(SOURCEDIR) \
--re-ignore ".*\.(ipynb_checkpoints|pyc|pyo|pyd|git)"
.PHONY: help Makefile compile clean
.PHONY: help Makefile compile clean serve
%: Makefile
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
......
# SGLang Documentation
We recommend new contributors start from writing documentation, which helps you quickly understand SGLang codebase. Most documentation files are located under the `docs/` folder. We prefer **Jupyter Notebooks** over Markdown so that all examples can be executed and validated by our docs CI pipeline.
## Docs Workflow
......@@ -20,10 +21,17 @@ Update your Jupyter notebooks in the appropriate subdirectories under `docs/`. I
# 1) Compile all Jupyter notebooks
make compile
# 2) Compile and Preview documentation locally
# 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
......@@ -90,7 +98,7 @@ For demonstrations in the docs, **prefer smaller models** to reduce memory consu
### **Prompt Alignment Example**
When designing prompts, ensure they align with SGLangs structured formatting. For example:
When designing prompts, ensure they align with SGLang's structured formatting. For example:
```python
prompt = """You are an AI assistant. Answer concisely and accurately.
......
......@@ -17,3 +17,4 @@ nbstripout
sphinxcontrib-mermaid
urllib3<2.0.0
gguf>=0.10.0
sphinx-autobuild
# Clean and serve documentation with auto-build
make clean
make html
python3 -m http.server --d _build/html 8003
make serve
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment