switch docs to mdbooks doc format (#218)

Move from mkdocs to mdbooks. Code heavily claude assisted.

Author: eugenevinitsky

.github/workflows/docs.yml

@@ -1,28 +1,30 @@
-name: Deploy MkDocs
+name: Deploy Docs
+
 on:
   push:
     branches: [main]
+    paths: [docs/**]
   workflow_dispatch:
 
 permissions:
-  contents: write  # allow pushing to gh-pages
+  contents: write
 
 jobs:
   build:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
-        with: { python-version: "3.x" }
-      - name: Install MkDocs deps
-        run: |
-          python -m pip install --upgrade pip
-          pip install -r docs/requirements.txt
-      - name: Build site
-        run: mkdocs build --strict
-      - name: Publish to GitHub Pages
-        uses: peaceiris/actions-gh-pages@v3
+
+      - name: Setup mdBook
+        uses: peaceiris/actions-mdbook@v2
+        with:
+          mdbook-version: 'latest'
+
+      - name: Build book
+        run: mdbook build docs
+
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v4
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: ./site
-          publish_branch: gh-pages
+          publish_dir: ./docs/book

.gitignore

@@ -188,3 +188,4 @@ artifacts/
 # Local drive renders
 pufferlib/resources/drive/output*.gif
 emsdk/
+docs/book/

README.md

@@ -181,10 +181,10 @@ puffer eval puffer_drive --eval.human-replay-eval True --load-model-path <your-t
 
 **Docs**
 
-A browsable documentation site now lives under `docs/` and is configured with MkDocs Material. To preview locally:
+A browsable documentation site now lives under `docs/` and is configured with mkbooks. To preview locally:
 ```
-uv pip install -r docs/requirements.txt  # or pip install -r docs/requirements.txt
-mkdocs serve
+brew install mdbook
+mdbook serve --open docs
 ```
 Open the served URL to see a local version of the docs.
 

docs/book.toml

@@ -0,0 +1,26 @@
+[book]
+title = "PufferDrive"
+description = "High-throughput autonomous driving simulator built on PufferLib."
+authors = ["Emerge-Lab"]
+language = "en"
+src = "src"
+
+[build]
+build-dir = "book"
+
+[output.html]
+default-theme = "light"
+preferred-dark-theme = "navy"
+git-repository-url = "https://github.com/Emerge-Lab/PufferDrive"
+site-url = "/PufferDrive/"
+additional-css = ["theme/extra.css"]
+additional-js = ["theme/mathjax.js"]
+mathjax-support = true
+
+[output.html.fold]
+enable = true
+level = 1
+
+[output.html.search]
+enable = true
+limit-results = 30

docs/requirements.txt

@@ -1,19 +1,27 @@
 # PufferDrive
 
+<p align="center">
+  <a href="https://github.com/Emerge-Lab/PufferDrive/stargazers"><img src="https://img.shields.io/github/stars/Emerge-Lab/PufferDrive?style=social" alt="GitHub stars"></a>
+  <a href="https://github.com/Emerge-Lab/PufferDrive/network/members"><img src="https://img.shields.io/github/forks/Emerge-Lab/PufferDrive?style=social" alt="GitHub forks"></a>
+  <a href="https://github.com/Emerge-Lab/PufferDrive"><img src="https://img.shields.io/github/watchers/Emerge-Lab/PufferDrive?style=social" alt="GitHub watchers"></a>
+</p>
+
 <div class="hero">
   <img src="images/pufferdrive.gif" alt="PufferDrive logo">
   <div>
     <p>PufferDrive is a high-throughput autonomous driving simulator built on <a href="https://puffer.ai">PufferLib</a>. Train and evaluate multi-agent driving policies with fast vectorized stepping, streamlined data conversion, and ready-made benchmarks.</p>
     <div class="cta">
-      <a class="primary" href="getting-started/">Start here: install & build</a>
+      <a class="primary" href="getting-started.html">Start here: install & build</a>
       <a href="#workflow">See the workflow</a>
     </div>
   </div>
 </div>
 
 ## Try it in your browser
 
-<iframe src="assets/game.html" title="PufferDrive Demo" width="1280" height="720" style="border: none; display: block; margin: 2rem auto;"></iframe>
+<div class="video-embed">
+<iframe src="assets/game.html" title="PufferDrive Demo" style="border: none;"></iframe>
+</div>
 
 <p style="text-align: center; color: #888; margin-top: 1rem;">
   Hold <strong>Left Shift</strong> and use arrow keys or <strong>WASD</strong> to control the vehicle. Hold <strong>space</strong> for first-person view and <strong>ctrl</strong> to see what your agent is seeing :)
@@ -40,19 +48,19 @@
     <div class="badge">Step 1</div>
     <h3>Install & Build</h3>
     <p>Set up the environment, install dependencies, and compile the native extensions.</p>
-    <a href="getting-started/">Open guide</a>
+    <a href="getting-started.html">Open guide</a>
   </div>
   <div class="step-card">
     <div class="badge">Step 2</div>
     <h3>Prepare Data</h3>
     <p>Download WOMD/GPUDrive datasets from Hugging Face and convert to map binaries.</p>
-    <a href="data/">Open guide</a>
+    <a href="data.html">Open guide</a>
   </div>
   <div class="step-card">
     <div class="badge">Step 3</div>
     <h3>Train & Evaluate</h3>
     <p>Train agents and evaluate them with WOSAC and human-replay benchmarks.</p>
-    <a href="evaluation/">Open guide</a>
+    <a href="evaluation.html">Open guide</a>
   </div>
 </div>
 

docs/index.md docs/src/README.mddocs/index.md renamed to docs/src/README.md

@@ -0,0 +1,25 @@
+# Summary
+
+[Getting started](README.md)
+
+# Documentation
+
+- [Getting Started](getting-started.md)
+- [Training Agents](train.md)
+- [Interact with Agents](interact-with-agents.md)
+- [Simulator](simulator.md)
+- [Interactive Scenario Editor](scene-editor.md)
+- [Visualizer](visualizer.md)
+
+# Data
+
+- [Data Sources & Preparation](data.md)
+
+# Benchmarks
+
+- [Evaluation Overview](evaluation.md)
+- [WOSAC](wosac.md)
+
+# Blog
+
+- [PufferDrive 2.0](pufferdrive-2.0.md)