Updates requirements.txt, moved java code examples into java files. (With Claude's help.)

snvgglebear · snvgglebear · commit e4d6be3c4f2e · 2026-03-30T23:35:51.000-04:00
diff --git a/docs/code_examples/RobotTelemetry.java b/docs/code_examples/RobotTelemetry.java
@@ -0,0 +1,14 @@
+// Snippet file: Robot.java integration code for the Telemetry subsystem.
+// These are not a standalone class — they show the relevant lines to add to Robot.java.
+
+// --8<-- [start:field-declaration]
+public static Telemetry m_telemetry;
+// --8<-- [end:field-declaration]
+
+// --8<-- [start:robot-init]
+m_telemetry = new Telemetry(); //This must be initialized after all other robot subsystems
+// --8<-- [end:robot-init]
+
+// --8<-- [start:periodic-update]
+Robot.m_telemetry.update();
+// --8<-- [end:periodic-update]
diff --git a/docs/code_examples/Telemetry.java b/docs/code_examples/Telemetry.java
@@ -0,0 +1,48 @@
+package frc.robot.subsystems;
+
+import edu.wpi.first.wpilibj.command.Subsystem;
+import edu.wpi.first.wpilibj.smartdashboard.SmartDashboard;
+import frc.robot.Robot;
+import frc.robot.commands.*;
+
+/**
+ * Add your docs here.
+ */
+// --8<-- [start:full-class]
+public class Telemetry extends Subsystem {
+    // Put methods for controlling this subsystem
+    // here. Call these from Commands.
+
+    public Telemetry() {
+        // --8<-- [start:constructor-drivetrain]
+        // Drivetrain
+        SmartDashboard.putData("Reset Drive Encoder", new DriveResetEncoder());
+        // --8<-- [end:constructor-drivetrain]
+
+        // --8<-- [start:constructor-shooter]
+        // Shooter
+        SmartDashboard.putData("Shooter Up", new ShooterUp());
+        SmartDashboard.putData("Shooter Down", new ShooterDown());
+        SmartDashboard.putData("Shooter Up Auto", new ShooterUpAuto());
+        // --8<-- [end:constructor-shooter]
+    }
+
+    public void update() {
+        // --8<-- [start:update-drivetrain]
+        // Drivetrain
+        SmartDashboard.putNumber("Drive Encoder Count", Robot.m_drivetrain.getDriveEncoderCount());
+        // --8<-- [end:update-drivetrain]
+
+        // --8<-- [start:update-shooter]
+        // Shooter
+        SmartDashboard.putBoolean("Shooter Switch", Robot.m_shooter.isShooterSwitchClosed());
+        // --8<-- [end:update-shooter]
+    }
+
+    @Override
+    public void initDefaultCommand() {
+        // Set the default command for a subsystem here.
+        // setDefaultCommand(new MySpecialCommand());
+    }
+}
+// --8<-- [end:full-class]
diff --git a/docs/programming/Elastic.md b/docs/programming/Elastic.md
@@ -40,8 +40,8 @@ In this section we will be going over
 !!! abstract ""
     **3)** Inside type:
 
-    ```java
-    SmartDashboard.putData("Reset Drive Encoder", new DriveResetEncoder());
+    ```java title="Telemetry.java"
+    --8<-- "docs/code_examples/Telemetry.java:constructor-drivetrain"
     ```
 
 !!! abstract ""
@@ -52,8 +52,8 @@ In this section we will be going over
 !!! abstract ""
     **5)** Inside type:
 
-    ```java
-    SmartDashboard.putNumber("Drivetrain Encoder Count", Robot.m_drivetrain.getDriveEncoderCount());
+    ```java title="Telemetry.java"
+    --8<-- "docs/code_examples/Telemetry.java:update-drivetrain"
     ```
 
 !!! abstract ""
@@ -66,45 +66,8 @@ In this section we will be going over
 
 	Your full **Telemetry.java** should look like this
 
-	```java
-	package frc.robot.subsystems;
-
-	import edu.wpi.first.wpilibj.command.Subsystem;
-	import edu.wpi.first.wpilibj.smartdashboard.SmartDashboard;
-	import frc.robot.Robot;
-	import frc.robot.commands.*;
-
-	/**
-	 * Add your docs here.
-	 */
-	public class Telemetry extends Subsystem {
-	    // Put methods for controlling this subsystem
-	    // here. Call these from Commands.
-
-	    public Telemetry() {
-	        // Drivetrain
-	        SmartDashboard.putData("Reset Drive Encoder", new DriveResetEncoder());
-
-	        // Shooter
-	        SmartDashboard.putData("Shooter Up", new ShooterUp());
-	        SmartDashboard.putData("Shooter Down", new ShooterDown());
-	        SmartDashboard.putData("Shooter Up Auto", new ShooterUpAuto());
-	    }
-
-	    public void update() {
-	        // Drivetrain
-	        SmartDashboard.putNumber("Drive Encoder Count", Robot.m_drivetrain.getDriveEncoderCount());
-
-	        // Shooter
-	        SmartDashboard.putBoolean("Shooter Switch", Robot.m_shooter.isShooterSwitchClosed());
-	    }
-
-	    @Override
-	    public void initDefaultCommand() {
-	        // Set the default command for a subsystem here.
-	        // setDefaultCommand(new MySpecialCommand());
-	    }
-	}
+	```java title="Telemetry.java"
+	--8<-- "docs/code_examples/Telemetry.java:full-class"
 	```
 
 ## Adding The Telemetry Subsystem to Robot.java
@@ -126,20 +89,20 @@ In this section we will be going over
 
 	The code you typed before **robotInit** should be this
 
-	```java
-	public static Telemetry m_telemetry;
+	```java title="Robot.java"
+	--8<-- "docs/code_examples/RobotTelemetry.java:field-declaration"
 	```
 
 	The code you typed in **robotInit** should be this
 
-	```java
-	m_telemetry = new Telemetry(); //This must be initialized after all other robot subsystems
+	```java title="Robot.java"
+	--8<-- "docs/code_examples/RobotTelemetry.java:robot-init"
 	```
 
 	The code you typed in **disabledPeriodic, autonomousPeriodic**, and **teleopPeriodic** should be this
 
-	```java
-	Robot.m_telemetry.update();
+	```java title="Robot.java"
+	--8<-- "docs/code_examples/RobotTelemetry.java:periodic-update"
 	```
 
 ## Opening Elastic
diff --git a/requirements.txt b/requirements.txt
@@ -1,5 +1,6 @@
 # Install requirements:
 # pip install -r requirements.txt
 mkdocs
+mkdocs-material
 pymdown-extensions
 mkdocs-minify-plugin
diff --git a/tutorial-platform-analysis.md b/tutorial-platform-analysis.md
@@ -177,15 +177,15 @@ JavaScript runtime Markdown renderer (MIT). No build step — Markdown is fetche
 
 ---
 
-### 8. mdBook
+### 8. [mdBook](https://rust-lang.github.io/mdBook/)
 
 Rust-based static site generator (Apache 2.0 / MIT) maintained by the Rust language team. Used for official Rust documentation.
 
-**Markdown Support:** CommonMark + some GFM extensions. Custom preprocessors (Rust or any subprocess). MathJax and Mermaid via preprocessors.
+**Markdown Support:** CommonMark + some GFM extensions. Custom preprocessors (Rust or any subprocess). [MathJax](https://www.mathjax.org/) and [Mermaid](https://mermaid.js.org/) via preprocessors.
 
 **Quiz Support:**
 - [`mdbook-quiz`](https://crates.io/crates/mdbook-quiz) (Apache 2.0 + MIT, v0.4.0, 148 GitHub stars): dedicated quiz preprocessor with questions authored in TOML files. Question types: ShortAnswer, MultipleChoice, and Tracing (predict Rust code output — Rust-specific). Used by Will Crichton's Rust learning materials at Brown University.
-- `mdbook-exercises` (December 2025): interactive exercise blocks with hints, solutions, Rust Playground integration, difficulty levels, time estimates.
+- [`mdbook-exercises`](https://github.com/rust-lang/mdBook/wiki/Third-party-plugins) (December 2025): interactive exercise blocks with hints, solutions, [Rust Playground](https://play.rust-lang.org/) integration, difficulty levels, time estimates.
 - `cache-answers = true` stores user answers in localStorage.
 
 **Progress Tracking:** `mdbook-quiz` with `cache-answers` persists quiz answers. No cross-book progress dashboard.
@@ -200,7 +200,7 @@ Rust-based static site generator (Apache 2.0 / MIT) maintained by the Rust langu
 
 ---
 
-### 9. LiaScript *(Purpose-Built)*
+### 9. [LiaScript](https://liascript.github.io/) *(Purpose-Built)*
 
 Open-source browser-based Markdown interpreter (MIT) extended with interactive learning primitives. Developed at TU Bergakademie Freiberg for Open Educational Resources. No server or build step required.
 
@@ -210,7 +210,7 @@ Open-source browser-based Markdown interpreter (MIT) extended with interactive l
 
 **Progress Tracking:** Built-in. LiaScript is a Progressive Web App (PWA) and stores course progress locally. Works offline after first load.
 
-**LMS Export:** SCORM 1.2 and SCORM 2004 export via `LiaScript-Exporter` CLI. Also exports to IMS, PDF, standalone web project, and Android APK. Most LMS-compatible platform reviewed — supports Moodle, ILIAS, OpenOlat, Canvas, Blackboard.
+**LMS Export:** SCORM 1.2 and SCORM 2004 export via [`LiaScript-Exporter`](https://github.com/LiaScript/LiaScript-Exporter) CLI. Also exports to IMS, PDF, standalone web project, and Android APK. Most LMS-compatible platform reviewed — supports [Moodle](https://moodle.org/), [ILIAS](https://www.ilias.de/), [OpenOlat](https://www.openolat.com/), [Canvas](https://www.instructure.com/canvas), [Blackboard](https://www.anthology.com/products/teaching-and-learning/blackboard-learn).
 
 **Hosting:** Content can be served from GitHub, GitLab, Nextcloud, Dropbox, IPFS, and more. The LiaScript interpreter loads from a CDN and processes a Markdown URL — content and renderer are completely decoupled.
 
@@ -246,7 +246,7 @@ Open-source browser-based Markdown interpreter (MIT) extended with interactive l
 
 ### Recommendation 1 — Minimal effort, maximum immediate capability
 
-**Stay on MkDocs + Material and add `mkdocs-quiz` and `mkdocs-material-mark-as-read`.**
+**Stay on [MkDocs](https://www.mkdocs.org/) + [Material](https://squidfunk.github.io/mkdocs-material/) and add [`mkdocs-quiz`](https://ewels.github.io/mkdocs-quiz/) and [`mkdocs-material-mark-as-read`](https://github.com/berk-karaal/mkdocs-material-mark-as-read).**
 
 ```bash
 pip install mkdocs-quiz mkdocs-material-mark-as-read
@@ -268,23 +268,23 @@ This delivers:
 
 No framework migration. No new toolchain. Existing content unchanged. Working quizzes within an hour of setup.
 
-The Material maintenance-mode concern is real but not urgent — existing functionality is stable. Monitor **Zensical** (the MIT-licensed successor by the same maintainer) as the natural long-term migration target with minimal content changes.
+The Material maintenance-mode concern is real but not urgent — existing functionality is stable. Monitor **[Zensical](https://github.com/zensical/zensical)** (the MIT-licensed successor by the same maintainer) as the natural long-term migration target with minimal content changes.
 
 ---
 
 ### Recommendation 2 — Migration path with maximum extensibility
 
-**Migrate to Docusaurus** if React expertise exists and the project needs quiz UI beyond multiple-choice (e.g., embedded code exercises, interactive robot simulators, code-grading sandboxes).
+**Migrate to [Docusaurus](https://docusaurus.io/)** if React expertise exists and the project needs quiz UI beyond multiple-choice (e.g., embedded code exercises, interactive robot simulators, code-grading sandboxes).
 
-MDX allows any React component in any page. The `@sp-days-framework/docusaurus-plugin-interactive-tasks` provides structured task completion with sidebar badges immediately. Custom quiz components can be built incrementally. Docusaurus has no maintenance concerns and the largest ecosystem.
+[MDX](https://mdxjs.com/) allows any React component in any page. The [`@sp-days-framework/docusaurus-plugin-interactive-tasks`](https://www.npmjs.com/package/@sp-days-framework/docusaurus-plugin-interactive-tasks) provides structured task completion with sidebar badges immediately. Custom quiz components can be built incrementally. Docusaurus has no maintenance concerns and the largest ecosystem.
 
 Migration cost: several days — `mkdocs.yml` nav → `docusaurus.config.js`, PyMdown admonition syntax → Docusaurus admonition syntax, custom overrides rebuild.
 
 ---
 
 ### Recommendation 3 — LMS integration requirement
 
-**Evaluate LiaScript** alongside the existing MkDocs reference site if FRC tutorial content needs to integrate with school LMS platforms (Moodle, Canvas) for grading or credit.
+**Evaluate [LiaScript](https://liascript.github.io/)** alongside the existing MkDocs reference site if FRC tutorial content needs to integrate with school LMS platforms ([Moodle](https://moodle.org/), [Canvas](https://www.instructure.com/canvas)) for grading or credit.
 
 LiaScript Markdown files can live in the same GitHub repository. SCORM export is a one-command CLI operation. The course content (Markdown) is shared; only the rendering layer differs between the MkDocs documentation site and the LiaScript course export.
 
