Merge dev: fix notebook filename convention in docs and Binder (fixes #1176)

Author: profvjreddi

binder/postBuild

@@ -18,14 +18,16 @@ echo "📓 Generating student notebooks from source..."
 for module_dir in src/*/; do
     module_name=$(basename "$module_dir")
     py_file="$module_dir/${module_name}.py"
+    # Strip numeric prefix for notebook name (e.g., "01_tensor" -> "tensor")
+    short_name="${module_name#*_}"
 
     if [ -f "$py_file" ]; then
         # Create output directory
         mkdir -p "modules/$module_name"
 
         # Convert .py to .ipynb using jupytext
         echo "   📝 Converting $module_name..."
-        jupytext --to notebook "$py_file" --output "modules/$module_name/${module_name}.ipynb" 2>/dev/null || {
+        jupytext --to notebook "$py_file" --output "modules/$module_name/${short_name}.ipynb" 2>/dev/null || {
             echo "   ⚠️  Warning: Could not convert $module_name"
         }
     fi

tinytorch/README.md

@@ -193,7 +193,7 @@ TinyTorch/
 │
 ├── modules/                    # 📓 Generated notebooks (learners work here)
 │   ├── 01_tensor/              # Auto-generated from src/
-│   │   ├── 01_tensor.ipynb     # Jupyter notebook for learning
+│   │   ├── tensor.ipynb         # Jupyter notebook for learning
 │   │   ├── README.md           # Practical implementation guide
 │   │   └── tensor.py           # Your implementation
 │   └── ...                     # (20 module directories)

tinytorch/binder/postBuild

@@ -15,14 +15,16 @@ echo "📓 Generating student notebooks from source..."
 for module_dir in src/*/; do
     module_name=$(basename "$module_dir")
     py_file="$module_dir/${module_name}.py"
+    # Strip numeric prefix for notebook name (e.g., "01_tensor" -> "tensor")
+    short_name="${module_name#*_}"
 
     if [ -f "$py_file" ]; then
         # Create output directory
         mkdir -p "modules/$module_name"
 
         # Convert .py to .ipynb using jupytext
         echo "   📝 Converting $module_name..."
-        jupytext --to notebook "$py_file" --output "modules/$module_name/${module_name}.ipynb" 2>/dev/null || {
+        jupytext --to notebook "$py_file" --output "modules/$module_name/${short_name}.ipynb" 2>/dev/null || {
             echo "   ⚠️  Warning: Could not convert $module_name"
         }
     fi

tinytorch/site/Makefile

@@ -29,6 +29,9 @@ serve: clean html
 pdf:
 	@echo "🔥 Building Tiny🔥Torch PDF via XeLaTeX..."
 	@echo ""
+	@# PDF build needs Mermaid CLI (for diagrams). Config uses npx; Node.js must be installed.
+	@command -v npx >/dev/null 2>&1 || { echo "❌ Error: npx not found. PDF build requires Node.js (for Mermaid diagrams). Install from https://nodejs.org/ or run: brew install node"; exit 1; }
+	@echo "✅ Mermaid CLI (via npx) available"
 	@# Step 1: Generate LaTeX (matches CI workflow)
 	@echo "📚 Generating LaTeX files..."
 	jupyter-book build . --builder latex --config _config_pdf.yml --toc _toc_pdf.yml
@@ -63,7 +66,7 @@ clean:
 install:
 	@echo "📦 Installing dependencies..."
 	pip install -U pip
-	pip install "jupyter-book<1.0"
+	pip install "jupyter-book>=1.0.0,<2.0.0"
 	pip install -r requirements.txt
 
 test:

tinytorch/site/_config_pdf.yml

@@ -13,10 +13,10 @@ description: >-
   Learn by implementing your own PyTorch-style framework with hands-on coding,
   real datasets, and production-ready practices.
 
-# Execution settings - disable for PDF
+# Execution settings - cache mode enables {glue} computed values in ABOUT.md files
 execute:
-  execute_notebooks: "off"
-  allow_errors: false
+  execute_notebooks: "cache"
+  allow_errors: true
   timeout: 300
 
 # Exclude patterns
@@ -51,12 +51,15 @@ sphinx:
     - sphinxcontrib.mermaid
   config:
     mermaid_version: "10.6.1"
+    # Use npx so PDF build works without global mermaid-cli (requires Node.js)
+    mermaid_cmd: "npx -y @mermaid-js/mermaid-cli"
     # Render mermaid as PDF for LaTeX
     # --pdfFit scales PDF to fit the diagram (not full page)
     # --scale 1.0 keeps diagrams at natural size (1.5 was too large for tall diagrams)
     mermaid_output_format: "pdf"
-    # Width 800 constrains diagram width; scale must be integer (1 = natural size)
-    mermaid_params: ['--pdfFit', '--scale', '1', '--width', '800', '--backgroundColor', 'white']
+    # Width 600 constrains diagram viewport; scale 1 = natural size
+    # Smaller viewport + pdfcrop produces tighter diagrams that don't stretch to full page width
+    mermaid_params: ['--pdfFit', '--scale', '1', '--width', '600', '--backgroundColor', 'white']
     # Use pdfcrop to trim whitespace from mermaid PDFs
     mermaid_pdfcrop: "pdfcrop"
     # Use professional sans-serif font for mermaid diagrams to match document
@@ -89,6 +92,9 @@ sphinx:
       papersize: 'letterpaper'
       pointsize: '10pt'
       figure_align: 'H'
+      # Pass 'export' option to adjustbox before Sphinx loads it (avoids option clash).
+      # This enables max width/height keys in \includegraphics for mermaid figure capping.
+      passoptionstopackages: '\PassOptionsToPackage{export}{adjustbox}'
       fontpkg: |
         % Professional academic font stack (TeX Gyre - available in TeX Live)
         \usepackage{fontspec}
@@ -109,6 +115,27 @@ sphinx:
         \usepackage{hyperref}
         \usepackage{float}
 
+        % Cap Mermaid diagram width at 75% of text width.
+        % sphinxcontrib-mermaid hardcodes width=\linewidth for all diagrams,
+        % which stretches small flowcharts to full page width. This override
+        % intercepts \includegraphics and uses adjustbox's max width for
+        % mermaid-*.pdf files while passing other images through unchanged.
+        % Note: adjustbox 'export' option passed via passoptionstopackages above.
+        \let\OrigIncludeGraphics\includegraphics
+        \makeatletter
+        \renewcommand{\includegraphics}[2][]{%
+          \begingroup
+          \def\@mermaidtest{mermaid-}%
+          \@expandtwoargs\in@{\@mermaidtest}{#2}%
+          \ifin@
+            \OrigIncludeGraphics[max width=0.75\linewidth,max height=0.45\textheight,keepaspectratio]{#2}%
+          \else
+            \OrigIncludeGraphics[#1]{#2}%
+          \fi
+          \endgroup
+        }
+        \makeatother
+
         % Better figure placement - keep figures inline with text
         \renewcommand{\topfraction}{0.9}
         \renewcommand{\bottomfraction}{0.9}
@@ -172,6 +199,13 @@ sphinx:
         \newunicodechar{ω}{$\omega$}
         \newunicodechar{✓}{\checkmark}
         \newunicodechar{✗}{$\times$}
+        % Box-drawing (terminal/code art) - TeX Gyre Cursor has no Unicode box glyphs
+        \newunicodechar{═}{\texttt{=}}
+        \newunicodechar{║}{\texttt{|}}
+        \newunicodechar{╔}{\texttt{+}}
+        \newunicodechar{╗}{\texttt{+}}
+        \newunicodechar{╚}{\texttt{+}}
+        \newunicodechar{╝}{\texttt{+}}
 
         % Syntax-highlighted code blocks with refined colors
         \usepackage{listings}

tinytorch/site/_static/custom.css

@@ -384,14 +384,16 @@ pre.mermaid {
     display: flex;
     align-items: center;
     font-size: 1.2rem;
-    font-weight: 600;
-    color: #f59e0b;
-    text-decoration: none;
+    font-weight: 700;
+    color: #fbbf24 !important;
+    text-decoration: none !important;
     letter-spacing: -0.01em;
+    text-shadow: 0 0 12px rgba(251, 191, 36, 0.3);
 }
 
 .tinytorch-bar-brand:hover {
-    color: #fbbf24;
+    color: #fde68a !important;
+    text-shadow: 0 0 16px rgba(251, 191, 36, 0.45);
 }
 
 .tinytorch-bar-brand .brand-fire {
@@ -485,26 +487,41 @@ pre.mermaid {
     background: rgba(249, 115, 22, 0.15);
 }
 
-/* Responsive: hide text on small screens, keep icons */
+/* ── Responsive: progressive disclosure across breakpoints ── */
+
+/* Tablet landscape / small desktop — drop date from version, shrink link padding */
+@media (max-width: 1024px) {
+    .tinytorch-bar-version .version-date {
+        display: none;
+    }
+
+    .tinytorch-bar-links a {
+        padding: 0.5rem 0.7rem;
+    }
+}
+
+/* Tablet portrait — icons only, shrink badge, ensure 44px touch targets */
 @media (max-width: 768px) {
     .tinytorch-bar-links .link-text {
         display: none;
     }
 
     .tinytorch-bar-links a {
-        padding: 0.5rem;
+        min-width: 44px;
+        min-height: 44px;
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        padding: 0;
     }
 
     .tinytorch-bar-links .link-icon {
-        font-size: 1.1rem;
+        font-size: 1.15rem;
     }
 
     .tinytorch-bar-badge {
-        display: none;
-    }
-
-    .tinytorch-bar-version {
-        display: none;
+        font-size: 0.65rem;
+        padding: 0.2rem 0.5rem;
     }
 
     .tinytorch-bar-left {
@@ -516,23 +533,42 @@ pre.mermaid {
     }
 
     .tinytorch-bar {
-        height: 44px;
+        height: 48px;
     }
 
-    /* Keep download link visible but compact on mobile */
-    .tinytorch-bar-links a.download-link {
-        padding: 0.4rem 0.6rem;
+    .tinytorch-bar-links {
+        gap: 0;
     }
 }
 
-/* Extra small screens - minimal spacing */
-@media (max-width: 480px) {
-    .tinytorch-bar-links {
-        gap: 0.1rem;
+/* Phone — hide badge, hide secondary links, keep compact version */
+@media (max-width: 600px) {
+    .tinytorch-bar-badge {
+        display: none;
     }
 
-    .tinytorch-bar-links a {
-        padding: 0.4rem;
+    .tinytorch-bar-links a.link-secondary {
+        display: none;
+    }
+
+    .tinytorch-bar-version {
+        font-size: 0.7rem;
+        padding: 0.2rem 0.5rem;
+    }
+
+    .tinytorch-bar {
+        height: 44px;
+    }
+
+    .tinytorch-bar-brand {
+        font-size: 1.05rem;
+    }
+}
+
+/* Small phone — hide version too, brand + 3 primary icons */
+@media (max-width: 420px) {
+    .tinytorch-bar-version {
+        display: none;
     }
 
     .tinytorch-bar-brand {
@@ -584,6 +620,18 @@ header.bd-header {
     margin-top: 3.5rem !important;
 }
 
+@media (max-width: 768px) {
+    header.bd-header {
+        margin-top: 2.75rem !important;
+    }
+}
+
+@media (max-width: 600px) {
+    header.bd-header {
+        margin-top: 2.5rem !important;
+    }
+}
+
 /* When announcement bar is present, add extra space */
 body.has-announcement header.bd-header {
     margin-top: 6rem !important;
@@ -593,6 +641,26 @@ body.has-announcement .tinytorch-bar {
     top: 2.5rem !important;
 }
 
+@media (max-width: 768px) {
+    body.has-announcement header.bd-header {
+        margin-top: 5rem !important;
+    }
+
+    body.has-announcement .tinytorch-bar {
+        top: 2.25rem !important;
+    }
+}
+
+@media (max-width: 600px) {
+    body.has-announcement header.bd-header {
+        margin-top: 4.5rem !important;
+    }
+
+    body.has-announcement .tinytorch-bar {
+        top: 2rem !important;
+    }
+}
+
 /* Hide icon links from sidebar completely - only show in top navbar */
 .bd-sidebar .icon-links,
 .bd-sidebar .navbar-icon-links,

tinytorch/site/_static/wip-banner.js

@@ -32,8 +32,8 @@ document.addEventListener('DOMContentLoaded', function() {
                     <a href="${siteRoot}intro.html" class="tinytorch-bar-brand">
                         Tiny<span class="brand-fire">🔥</span>Torch
                     </a>
+                    <a href="https://github.com/harvard-edge/cs249r_book/releases" target="_blank" rel="noopener noreferrer" class="tinytorch-bar-version" title="View releases on GitHub"><span class="version-number">v${TINYTORCH_VERSION}</span><span class="version-date"> · ${TINYTORCH_RELEASE_DATE}</span></a>
                     <span class="tinytorch-bar-badge">Under Construction</span>
-                    <a href="https://github.com/harvard-edge/cs249r_book/releases" target="_blank" rel="noopener noreferrer" class="tinytorch-bar-version" title="View releases on GitHub">v${TINYTORCH_VERSION} · ${TINYTORCH_RELEASE_DATE}</a>
                 </div>
                 <div class="tinytorch-bar-links">
                     <a href="${siteRoot}_static/downloads/TinyTorch-Guide.pdf" class="download-link" title="Download Course Guide (PDF)">
@@ -44,19 +44,19 @@ document.addEventListener('DOMContentLoaded', function() {
                         <span class="link-icon">↗</span>
                         <span class="link-text">Paper</span>
                     </a>
-                    <a href="https://mlsysbook.ai" target="_blank">
+                    <a href="https://mlsysbook.ai" target="_blank" class="link-secondary">
                         <span class="link-icon">📖</span>
                         <span class="link-text">MLSysBook</span>
                     </a>
-                    <a href="#" class="subscribe-trigger" onclick="event.preventDefault(); if(window.openSubscribeModal) openSubscribeModal();">
+                    <a href="#" class="subscribe-trigger link-secondary" onclick="event.preventDefault(); if(window.openSubscribeModal) openSubscribeModal();">
                         <span class="link-icon">✉️</span>
                         <span class="link-text">Subscribe</span>
                     </a>
                     <a href="https://github.com/harvard-edge/cs249r_book" target="_blank">
                         <span class="link-icon">⭐</span>
                         <span class="link-text">Star</span>
                     </a>
-                    <a href="${siteRoot}community.html" target="_blank">
+                    <a href="${siteRoot}community.html" target="_blank" class="link-secondary">
                         <span class="link-icon">🌍</span>
                         <span class="link-text">Community</span>
                     </a>

tinytorch/site/_toc_pdf.yml

@@ -121,6 +121,13 @@ parts:
   - file: conclusion
     title: "You Built Something Real"
 
+# Community (referenced from TITO overview)
+- caption: Community
+  numbered: false
+  chapters:
+  - file: community
+    title: "Community Guide"
+
 # Appendix
 - caption: Appendix
   numbered: false

tinytorch/site/getting-started.md

@@ -104,10 +104,10 @@ This opens the module notebook and tracks your progress.
 
 ### Work in the notebook
 
-Edit `modules/01_tensor/01_tensor.ipynb` in Jupyter:
+Edit `modules/01_tensor/tensor.ipynb` in Jupyter:
 
 ```bash
-jupyter lab modules/01_tensor/01_tensor.ipynb
+jupyter lab modules/01_tensor/tensor.ipynb
 ```
 
 You'll implement:

tinytorch/site/tito/modules.md

@@ -409,11 +409,11 @@ src/ ← Developer source code
 
 modules/ ← Generated notebooks (students use)
 ├── 01_tensor/
-│ └── 01_tensor.ipynb ← AUTO-GENERATED for students
+│ └── tensor.ipynb ← AUTO-GENERATED for students
 ├── 02_activations/
-│ └── 02_activations.ipynb ← AUTO-GENERATED for students
+│ └── activations.ipynb ← AUTO-GENERATED for students
 └── 03_layers/
- └── 03_layers.ipynb ← AUTO-GENERATED for students
+ └── layers.ipynb ← AUTO-GENERATED for students
 ```
 
 ### Where Code Exports