Support Markdown/Notebook-Friendly Documentation Export for Downstream Integration

[klhhhhh]

Motivation

Modifications

Accuracy Tests

Benchmarking and Profiling

Checklist

• Format your code according to the Format code with pre-commit.
• Add unit tests according to the Run and add unit tests.
• Update documentation according to Write documentations.
• Provide accuracy and speed benchmark results according to Test the accuracy and Benchmark the speed.
• Follow the SGLang code style guidance.

Review Process

1. Ping Merge Oncalls to start the PR flow. See the PR Merge Process.
2. Get approvals from CODEOWNERS and other reviewers.
3. Trigger CI tests with comments or contact authorized users to do so.
   • /tag-run-ci-label, /rerun-failed-ci, /tag-and-rerun-ci
4. After green CI and required approvals, ask Merge Oncalls to merge.

[gemini-code-assist]

Summary of Changes

Hello @klhhhhh, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request enhances the documentation build process by adding a new capability to export Jupyter Notebooks into Markdown format. This change is crucial for enabling more flexible and notebook-friendly documentation for downstream integration, allowing content to be consumed in various formats without requiring notebook execution.

Highlights

• New Makefile Target: Introduced a markdown target in docs/Makefile to convert Jupyter Notebooks to Markdown files.
• Notebook to Markdown Conversion: The new target utilizes jupyter nbconvert to export .ipynb files as .md files, facilitating documentation export without execution.
• Output Directory: Converted Markdown files are stored in a new _build/md directory within the documentation build structure.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Changelog

• docs/Makefile
  • Added a new markdown target for converting Jupyter Notebooks to Markdown.
  • Implemented logic to use jupyter nbconvert for the conversion.
  • Configured output to a _build/md directory.

Ignored Files

• Ignored by pattern: .github/workflows/** (1)
  • .github/workflows/release-docs.yml

Activity

• The author, klhhhhh, created this pull request to add support for Markdown/Notebook-Friendly Documentation Export.
• The initial commit introduces a new markdown target in docs/Makefile.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[klhhhhh]

Fix issue #18081

[gemini-code-assist]

Code Review

This pull request adds a new markdown target to the docs/Makefile to export Jupyter notebooks to Markdown files. The implementation is functionally correct and uses parallel for concurrency, which is great.

My review includes a suggestion to simplify the script within the parallel command by using its built-in features and leveraging jupyter nbconvert's options more effectively. This will improve the readability and maintainability of the Makefile.

[gemini-code-assist]

The script within parallel can be significantly simplified by using GNU Parallel's built-in replacement strings and leveraging jupyter nbconvert's ability to create output directories. This will make the script more concise and idiomatic.

You can replace the current block of shell commands with a single jupyter nbconvert call:

jupyter nbconvert --to markdown "{}" \
    --output "{/.}.md" \
    --output-dir "$(BUILDDIR)/md/{//}" \
    >/dev/null;

Here's what the replacement strings do:

• {}: The full path to the notebook.
• {//}: The directory name of the notebook.
• {/.}: The basename of the notebook without the extension.

The mkdir -p command is also redundant because jupyter nbconvert creates the output directory specified by --output-dir if it doesn't exist.

[zhaochenyang20]

Great

[klhhhhh]

Documentation Build and Markdown Export Workflow

Overview

The SGLang documentation pipeline is based on Sphinx and supports rendering Jupyter notebooks (.ipynb) into HTML for web display.
To support downstream documentation systems that cannot ingest HTML, we introduce an additional Markdown export path while keeping the existing build logic unchanged.

The key idea is to reuse the existing build directory (_build/html) and colocate Markdown artifacts alongside the rendered website.

---

Current Documentation Build Flow

1. 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
• 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 before rendering.

---

2. 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.

---

Added Capability: Markdown Export (make markdown)

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

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

---

Recommended CI Execution Order

In CI, the documentation pipeline follows this order:

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

This ensures that:

• The website renders correctly
• Markdown artifacts reflect the same notebook state as the web pages

[zhaochenyang20]

Most of the documents are lost? 🤔 And, as I said, we want to make index.rst also in the markdown.