Clean up documentation structure and update workflow files

Author: GitHub Actions

.github/scripts/build_docs.py

@@ -0,0 +1,54 @@
+#!/usr/bin/env python3
+"""
+Simple documentation builder for deploy-to-pages.sh
+Builds mdBook documentation in software/book/book/ directory.
+"""
+
+import sys
+import subprocess
+from pathlib import Path
+
+def run_command(command: str, cwd: Path) -> bool:
+    """Run a shell command and return success status."""
+    try:
+        result = subprocess.run(command, shell=True, cwd=cwd, check=True)
+        return True
+    except subprocess.CalledProcessError as e:
+        print(f"ERROR: Command failed: {command}")
+        return False
+
+def main():
+    """Build documentation for GitHub Pages deployment."""
+    # Get project root (2 levels up from scripts)
+    project_root = Path(__file__).parent.parent.parent
+    book_path = project_root / "software" / "book"
+    extract_script = Path(__file__).parent / "smart-extract-docs.py"
+    
+    print("Building documentation...")
+    
+    # Step 1: Extract content from READMEs
+    print("Extracting content from README files...")
+    if not run_command(f"python3 {extract_script}", project_root):
+        sys.exit(1)
+    
+    # Step 2: Build mdBook
+    print("Building mdBook...")
+    if not run_command("mdbook build", book_path):
+        sys.exit(1)
+    
+    # Step 3: Verify build
+    built_path = book_path / "book"
+    if not built_path.exists():
+        print("ERROR: Build directory not created")
+        sys.exit(1)
+    
+    index_html = built_path / "index.html"
+    if not index_html.exists():
+        print("ERROR: index.html not found")
+        sys.exit(1)
+    
+    print("SUCCESS: Documentation built successfully")
+    print(f"Output directory: {built_path}")
+
+if __name__ == "__main__":
+    main()

.github/scripts/config.sh

@@ -0,0 +1,40 @@
+#!/bin/bash
+# Configuration file for documentation deployment
+# This file contains all configurable parameters to avoid hardcoded values
+
+# Navigation Links
+SHOP_URL="https://uelectronics.com/"
+REPO_URL="https://github.com/UNIT-Electronics-MX/unit_jun_r3_development_board"
+
+# Icons (using Unicode emojis)
+SHOP_ICON="🛒"
+REPO_ICON="📋"
+
+# Titles
+SHOP_TITLE="Shop"
+REPO_TITLE="Repository"
+
+# Styling
+LINK_COLOR="#666"
+LINK_PADDING="4px"
+LINK_FONT_SIZE="14px"
+LINK_MARGIN="4px"
+BORDER_COLOR="#ddd"
+BORDER_RADIUS="3px"
+LINK_WIDTH="24px"
+LINK_HEIGHT="24px"
+LINE_HEIGHT="16px"
+
+# Hover states
+HOVER_BORDER_COLOR="#999"
+HOVER_BG_COLOR="#f5f5f5"
+
+# Timing
+NAVBAR_INJECTION_DELAY="100"
+
+# Build directories
+BUILD_DIR="software/book/book"
+DOCS_DIR="docs"
+
+# Git configuration
+GIT_BRANCH="main"

.github/scripts/deploy-to-pages.sh

@@ -0,0 +1,88 @@
+#!/bin/bash
+# Build documentation for GitHub Actions deployment
+# This script builds documentation using configurable parameters (no hardcoded values)
+
+echo " Building documentation for GitHub Actions..."
+
+# Load configuration with robust path handling
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "${SCRIPT_DIR}/config.sh"
+
+# Build documentation (does NOT modify docs/ directory)
+echo " Building documentation..."
+python3 .github/scripts/build_docs.py
+
+if [ $? -ne 0 ]; then
+    echo " Build failed!"
+    exit 1
+fi
+
+# Check if book directory was created
+if [ ! -d "${BUILD_DIR}" ]; then
+    echo " ${BUILD_DIR}/ directory not found after build!"
+    exit 1
+fi
+
+echo "Files in ${BUILD_DIR}/ directory:"
+ls -la "${BUILD_DIR}/"
+
+# Load navbar builder functions
+source "$(dirname "$0")/navbar-builder.sh"
+
+# Build navbar using configurable parameters
+build_navbar_into_files "${BUILD_DIR}"
+
+echo "Documentation built successfully!"
+
+# Copy to docs/ directory for GitHub Pages deployment
+echo "Copying documentation to ${DOCS_DIR}/ directory..."
+
+# Remove existing content from docs/ (except PDFs if any)
+find "${DOCS_DIR}" -name "*.html" -delete 2>/dev/null || true
+find "${DOCS_DIR}" -name "*.css" -delete 2>/dev/null || true
+find "${DOCS_DIR}" -name "*.js" -delete 2>/dev/null || true
+find "${DOCS_DIR}" -type d -name "FontAwesome" -exec rm -rf {} + 2>/dev/null || true
+find "${DOCS_DIR}" -type d -name "fonts" -exec rm -rf {} + 2>/dev/null || true
+find "${DOCS_DIR}" -type d -name "css" -exec rm -rf {} + 2>/dev/null || true
+find "${DOCS_DIR}" -type d -name "resources" -exec rm -rf {} + 2>/dev/null || true
+find "${DOCS_DIR}" -type d -name "hardware" -exec rm -rf {} + 2>/dev/null || true
+find "${DOCS_DIR}" -type d -name "software" -exec rm -rf {} + 2>/dev/null || true
+
+# Copy new built content to docs/
+cp -r "${BUILD_DIR}"/* "${DOCS_DIR}/"
+
+echo "Updated ${DOCS_DIR}/ directory contents:"
+ls -la "${DOCS_DIR}/" | head -10
+
+# Force commit the updated docs/ directory
+echo "Committing updated documentation to ${DOCS_DIR}/..."
+git add "${DOCS_DIR}/"
+
+# Check if there are changes to commit
+if git diff --cached --quiet; then
+    echo "ℹNo changes detected in ${DOCS_DIR}/ directory"
+else
+    # Force commit changes
+    echo "Committing documentation updates..."
+    git commit -m "Auto-update documentation in ${DOCS_DIR}/
+
+    - Built from latest README content  
+    - Generated: $(date)
+    - Updated navbar with configurable ${SHOP_TITLE} and ${REPO_TITLE} icons
+    - Commit: $(git rev-parse --short HEAD)"
+    
+    # Push to repository to trigger deployment
+    echo "📡 Pushing to trigger GitHub Pages deployment..."
+    git push origin "${GIT_BRANCH}"
+    
+    if [ $? -eq 0 ]; then
+        echo "Documentation successfully updated and pushed!"
+        echo "GitHub Pages will deploy automatically in a few minutes"
+        echo "Check deployment status at: ${REPO_URL}/actions"
+    else
+        echo "Failed to push to repository!"
+        exit 1
+    fi
+fi
+
+echo "Documentation deployment process completed!"

.github/scripts/navbar-builder.sh

@@ -0,0 +1,72 @@
+#!/bin/bash
+# Navbar builder functions
+# This file contains reusable functions for building navbar elements
+
+# Load configuration with robust path handling
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "${SCRIPT_DIR}/config.sh"
+
+# Function to generate navbar JavaScript injection
+generate_navbar_js() {
+    cat << EOF
+<script>
+document.addEventListener("DOMContentLoaded", function() {
+    setTimeout(function() {
+        const menuBar = document.querySelector(".menu-bar .right-buttons");
+        if (menuBar) {
+            // Shop Link
+            const shopLink = document.createElement("a");
+            shopLink.href = "${SHOP_URL}";
+            shopLink.target = "_blank";
+            shopLink.innerHTML = "${SHOP_ICON}";
+            shopLink.title = "${SHOP_TITLE}";
+            shopLink.style.cssText = "color: ${LINK_COLOR}; text-decoration: none; padding: ${LINK_PADDING}; font-size: ${LINK_FONT_SIZE}; margin-right: ${LINK_MARGIN}; border: 1px solid ${BORDER_COLOR}; border-radius: ${BORDER_RADIUS}; transition: all 0.2s ease; display: inline-block; text-align: center; width: ${LINK_WIDTH}; height: ${LINK_HEIGHT}; line-height: ${LINE_HEIGHT};";
+            shopLink.onmouseover = function() { this.style.borderColor = "${HOVER_BORDER_COLOR}"; this.style.backgroundColor = "${HOVER_BG_COLOR}"; };
+            shopLink.onmouseout = function() { this.style.borderColor = "${BORDER_COLOR}"; this.style.backgroundColor = "transparent"; };
+            
+            // Repository Link
+            const repoLink = document.createElement("a");
+            repoLink.href = "${REPO_URL}";
+            repoLink.target = "_blank";
+            repoLink.innerHTML = "${REPO_ICON}";
+            repoLink.title = "${REPO_TITLE}";
+            repoLink.style.cssText = "color: ${LINK_COLOR}; text-decoration: none; padding: ${LINK_PADDING}; font-size: ${LINK_FONT_SIZE}; margin-right: ${LINK_MARGIN}; border: 1px solid ${BORDER_COLOR}; border-radius: ${BORDER_RADIUS}; transition: all 0.2s ease; display: inline-block; text-align: center; width: ${LINK_WIDTH}; height: ${LINK_HEIGHT}; line-height: ${LINE_HEIGHT};";
+            repoLink.onmouseover = function() { this.style.borderColor = "${HOVER_BORDER_COLOR}"; this.style.backgroundColor = "${HOVER_BG_COLOR}"; };
+            repoLink.onmouseout = function() { this.style.borderColor = "${BORDER_COLOR}"; this.style.backgroundColor = "transparent"; };
+            
+            // Insert links in correct order
+            menuBar.insertBefore(repoLink, menuBar.firstChild);
+            menuBar.insertBefore(shopLink, menuBar.firstChild);
+        }
+    }, ${NAVBAR_INJECTION_DELAY});
+});
+</script>
+EOF
+}
+
+# Function to build navbar into HTML files
+build_navbar_into_files() {
+    local build_dir="$1"
+    
+    echo " Building configurable navbar links..."
+    
+    # Generate the JavaScript code
+    local navbar_js=$(generate_navbar_js)
+    
+    # Create temporary file with the JavaScript
+    local temp_js_file=$(mktemp)
+    echo "$navbar_js" > "$temp_js_file"
+    
+    # Inject into all HTML files
+    for html_file in "${build_dir}"/*.html "${build_dir}"/*/*.html "${build_dir}"/*/*/*.html; do
+        if [ -f "$html_file" ]; then
+            # Insert navbar JavaScript before closing body tag (without escape characters)
+            sed -i "/<\/body>/r $temp_js_file" "$html_file"
+        fi
+    done
+    
+    # Clean up
+    rm "$temp_js_file"
+    
+    echo "Navbar build completed using configuration variables!"
+}