From b9b3b098b9e238ab745cb955a8899d1f24a532ba Mon Sep 17 00:00:00 2001 From: samzong Date: Thu, 6 Mar 2025 14:39:34 +0800 Subject: [PATCH] feat: support docs auto live-reload with sphinx-autobuild (#4111) Signed-off-by: samzong Co-authored-by: zhaochenyang20 --- docs/Makefile | 14 +++++++++++++- docs/README.md | 12 ++++++++++-- docs/requirements.txt | 1 + docs/serve.sh | 4 ++-- 4 files changed, 26 insertions(+), 5 deletions(-) diff --git a/docs/Makefile b/docs/Makefile index 7c1888f2f..9f4052639 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -1,11 +1,16 @@ # 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) diff --git a/docs/README.md b/docs/README.md index 2e4fb53e4..0dfadb1d0 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,4 +1,5 @@ # 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 SGLang’s 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. diff --git a/docs/requirements.txt b/docs/requirements.txt index 59c475775..1a7e5d4eb 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -17,3 +17,4 @@ nbstripout sphinxcontrib-mermaid urllib3<2.0.0 gguf>=0.10.0 +sphinx-autobuild diff --git a/docs/serve.sh b/docs/serve.sh index ed35ba1f3..049f767cf 100644 --- a/docs/serve.sh +++ b/docs/serve.sh @@ -1,3 +1,3 @@ +# Clean and serve documentation with auto-build make clean -make html -python3 -m http.server --d _build/html 8003 +make serve