docs: add multiple languages (Rust/JS/Python) to book

.github/workflows/rust.yml

@@ -82,7 +82,7 @@ jobs:
       - name: Install Rust toolchain
         uses: moonrepo/setup-rust@ede6de059f8046a5e236c94046823e2af11ca670 # v1.2.2
         with:
-          bins: cargo-nextest,just,mdbook
+          bins: cargo-nextest,just,mdbook,mdbook-langtabs
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 

.github/workflows/test-book-examples.yml

@@ -0,0 +1,300 @@
+name: Test Book Examples
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'book/src/**/*.md'
+      - 'book/scripts/**'
+      - '.github/workflows/test-book-examples.yml'
+  pull_request:
+    branches: [main]
+    paths:
+      - 'book/src/**/*.md'
+      - 'book/scripts/**'
+      - '.github/workflows/test-book-examples.yml'
+  # Allow manual triggering
+  workflow_dispatch:
+
+jobs:
+  test-examples:
+    name: Test Documentation Examples
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      # Set up Rust
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          toolchain: stable
+
+      - name: Cache Rust dependencies
+        uses: Swatinem/rust-cache@v2
+
+      # Set up Node.js
+      - name: Install Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "npm"
+          cache-dependency-path: js/package-lock.json
+
+      # Set up Python
+      - name: Install Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: "pip"
+
+      # Build augurs packages
+      - name: Install wasm-pack
+        run: cargo install wasm-pack
+
+      - name: Install just
+        uses: taiki-e/install-action@v2
+        with:
+          tool: just
+
+      - name: Build augurs JavaScript packages
+        run: |
+          cd js
+          just build
+        continue-on-error: true
+
+      - name: Build augurs for Python
+        run: |
+          cd crates/pyaugurs
+          python -m venv .venv
+          .venv/bin/pip install maturin numpy
+          .venv/bin/maturin develop --release
+        continue-on-error: true
+
+      # Run test script
+      - name: Test examples with Python script
+        run: |
+          cd book
+          python3 scripts/test_examples.py
+
+      # Upload artifacts on failure
+      - name: Upload test artifacts
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: test-examples-output
+          path: book/.test-examples/
+          retention-days: 7
+
+  # Optional: Check that examples are present in docs
+  verify-coverage:
+    name: Verify Example Coverage
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Check for code examples in key files
+        run: |
+          echo "Checking for code examples in documentation..."
+
+          # Files that should have code examples
+          FILES=(
+            "book/src/getting-started/installation.md"
+            "book/src/getting-started/quick-start.md"
+          )
+
+          MISSING=0
+
+          for file in "${FILES[@]}"; do
+            if [ ! -f "$file" ]; then
+              echo "⚠ File not found: $file"
+              continue
+            fi
+
+            # Check for langtabs sections
+            if ! grep -q "<!-- langtabs-start -->" "$file"; then
+              echo "✗ Missing langtabs in: $file"
+              MISSING=$((MISSING + 1))
+            else
+              # Count code blocks
+              RUST_COUNT=$(grep -c '```rust' "$file" || true)
+              JS_COUNT=$(grep -c '```javascript' "$file" || true)
+              PY_COUNT=$(grep -c '```python' "$file" || true)
+
+              echo "✓ $file has examples:"
+              echo "  - Rust: $RUST_COUNT"
+              echo "  - JavaScript: $JS_COUNT"
+              echo "  - Python: $PY_COUNT"
+
+              # Warn if languages are imbalanced
+              if [ $RUST_COUNT -gt 0 ] && [ $JS_COUNT -eq 0 ]; then
+                echo "  ⚠ Missing JavaScript examples"
+              fi
+              if [ $RUST_COUNT -gt 0 ] && [ $PY_COUNT -eq 0 ]; then
+                echo "  ⚠ Missing Python examples"
+              fi
+            fi
+          done
+
+          if [ $MISSING -gt 0 ]; then
+            echo ""
+            echo "Some key documentation files are missing code examples."
+            echo "This is a warning, not a failure."
+          fi
+
+  # Optional: Test specific language examples separately for better debugging
+  test-rust-examples:
+    name: Test Rust Examples Only
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Install Python for test script
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Extract and test Rust examples
+        run: |
+          cd book
+          python3 -c "
+          import sys
+          sys.path.insert(0, 'scripts')
+          from test_examples import extract_code_blocks, find_markdown_files, test_code_block
+          from pathlib import Path
+
+          book_src = Path('src')
+          blocks = []
+          for md_file in find_markdown_files(book_src):
+              blocks.extend([b for b in extract_code_blocks(md_file) if b.language.lower() in ('rust', 'rs')])
+
+          print(f'Found {len(blocks)} Rust code blocks')
+
+          from tempfile import TemporaryDirectory
+          with TemporaryDirectory() as td:
+              temp_dir = Path(td)
+              (temp_dir / 'rust').mkdir()
+              temp_dirs = {'rust': temp_dir / 'rust'}
+
+              failed = 0
+              for i, block in enumerate(blocks):
+                  result = test_code_block(block, temp_dirs, i)
+                  if result.success is False:
+                      failed += 1
+
+              sys.exit(1 if failed > 0 else 0)
+          "
+
+  test-js-examples:
+    name: Test JavaScript Examples Only
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Install augurs for JavaScript
+        run: |
+          cd js
+          npm ci || npm install
+        continue-on-error: true
+
+      - name: Install Python for test script
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Extract and test JavaScript examples
+        run: |
+          cd book
+          python3 -c "
+          import sys
+          sys.path.insert(0, 'scripts')
+          from test_examples import extract_code_blocks, find_markdown_files, test_code_block
+          from pathlib import Path
+
+          book_src = Path('src')
+          blocks = []
+          for md_file in find_markdown_files(book_src):
+              blocks.extend([b for b in extract_code_blocks(md_file) if b.language.lower() in ('javascript', 'js')])
+
+          print(f'Found {len(blocks)} JavaScript code blocks')
+
+          from tempfile import TemporaryDirectory
+          with TemporaryDirectory() as td:
+              temp_dir = Path(td)
+              (temp_dir / 'js').mkdir()
+              temp_dirs = {'js': temp_dir / 'js'}
+
+              failed = 0
+              for i, block in enumerate(blocks):
+                  result = test_code_block(block, temp_dirs, i)
+                  if result.success is False:
+                      failed += 1
+
+              sys.exit(1 if failed > 0 else 0)
+          "
+
+  test-python-examples:
+    name: Test Python Examples Only
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install augurs for Python
+        run: |
+          pip install maturin numpy
+          cd crates/pyaugurs
+          maturin develop
+        continue-on-error: true
+
+      - name: Extract and test Python examples
+        run: |
+          cd book
+          python3 -c "
+          import sys
+          sys.path.insert(0, 'scripts')
+          from test_examples import extract_code_blocks, find_markdown_files, test_code_block
+          from pathlib import Path
+
+          book_src = Path('src')
+          blocks = []
+          for md_file in find_markdown_files(book_src):
+              blocks.extend([b for b in extract_code_blocks(md_file) if b.language.lower() in ('python', 'py')])
+
+          print(f'Found {len(blocks)} Python code blocks')
+
+          from tempfile import TemporaryDirectory
+          with TemporaryDirectory() as td:
+              temp_dir = Path(td)
+              (temp_dir / 'python').mkdir()
+              temp_dirs = {'python': temp_dir / 'python'}
+
+              failed = 0
+              for i, block in enumerate(blocks):
+                  result = test_code_block(block, temp_dirs, i)
+                  if result.success is False:
+                      failed += 1
+
+              sys.exit(1 if failed > 0 else 0)
+          "

book/book.toml

@@ -6,3 +6,10 @@ title = "augurs - a time series toolkit"
 
 [rust]
 edition = "2021"
+
+[preprocessor.langtabs]
+command = "mdbook-langtabs"
+
+[output.html]
+additional-css = ["langtabs.css"]
+additional-js = ["langtabs.js"]

book/justfile

@@ -6,3 +6,27 @@ build:
 
 test:
     mdbook test -L ../target/debug/deps
+
+# Test all code examples in documentation
+test-examples:
+    python3 scripts/test_examples.py
+
+# Test only Rust examples
+test-rust:
+    python3 scripts/test_examples.py --lang rust
+
+# Test only JavaScript examples
+test-javascript:
+    python3 scripts/test_examples.py --lang javascript
+
+# Test only Python examples
+test-python:
+    python3 scripts/test_examples.py --lang python
+
+# Run all tests (mdbook + examples)
+test-all: test test-examples
+
+# Install mdbook-langtabs preprocessor
+install-langtabs:
+    cargo install mdbook-langtabs
+    mdbook-langtabs install .