From 1636e255fe5226ba69a119ab63e4cbb4bed5f115 Mon Sep 17 00:00:00 2001 From: Jukka Aho Date: Sun, 9 Nov 2025 04:45:12 +0200 Subject: [PATCH] docs: Add YAML front matter to all documentation files **Purpose:** Prepare documentation for publishing as blog posts or book **YAML Headers Include:** - title: Document title - subtitle: Optional subtitle for context - description: Brief summary for SEO/indexing - date: Creation date - updated: Last update date (for status docs) - author: Jukka Aho - categories: Taxonomic classification - keywords: Search/indexing keywords - audience: Target reader (users/contributors/researchers) - level: Difficulty level (beginner/intermediate/advanced/expert) - type: Document type (manual/guide/theory/benchmark/status) - series: Which manual it belongs to - chapter: Book structure (for The JuliaFEM Book) - status: Current state (completed/work in progress/active maintenance) - math: Whether document contains mathematical notation - prerequisites: Required background knowledge - tools: Software/packages used (for benchmarks) - context: Background information **Files Updated:** - docs/README.md (main index) - docs/user/README.md (user manual index) - docs/contributor/README.md (contributor manual index) - docs/book/README.md (book index) - docs/contributor/testing_philosophy.md - docs/contributor/status.md - docs/contributor/test_fixes_needed.md - docs/book/lagrange_basis_functions.md - docs/book/benchmarks/shape_function_derivatives_ad_vs_manual.md - scripts/README.md **Benefits:** - Ready for static site generators (Jekyll, Hugo, MkDocs) - Can generate book with proper metadata - SEO-friendly with descriptions and keywords - Clear audience/level targeting - Trackable with dates and status - Organized by series and chapters **Compatible With:** - Jekyll (GitHub Pages) - Hugo (fast static site generator) - MkDocs (Python-based documentation) - Jupyter Book (interactive books) - Docusaurus (React-based docs) - Custom publishing scripts --- docs/README.md | 10 ++++++++++ docs/book/README.md | 14 ++++++++++++++ ...shape_function_derivatives_ad_vs_manual.md | 19 +++++++++++++++++++ docs/book/lagrange_basis_functions.md | 17 +++++++++++++++++ docs/contributor/README.md | 12 ++++++++++++ docs/contributor/status.md | 16 +++++++++++++++- docs/contributor/test_fixes_needed.md | 15 +++++++++++++++ docs/contributor/testing_philosophy.md | 15 ++++++++++++++- docs/user/README.md | 12 ++++++++++++ scripts/README.md | 12 ++++++++++++ 10 files changed, 140 insertions(+), 2 deletions(-) diff --git a/docs/README.md b/docs/README.md index 82e5068..3ec299f 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,3 +1,13 @@ +--- +title: "JuliaFEM Documentation" +description: "Three-tier documentation structure for users, contributors, and researchers" +date: 2025-11-09 +author: "Jukka Aho" +categories: ["documentation", "guide"] +keywords: ["juliafem", "finite element", "documentation", "manual"] +type: "index" +--- + # JuliaFEM Documentation Welcome! JuliaFEM documentation is organized into **three manuals** for three different audiences: diff --git a/docs/book/README.md b/docs/book/README.md index 71b05d3..5c262de 100644 --- a/docs/book/README.md +++ b/docs/book/README.md @@ -1,3 +1,17 @@ +--- +title: "The JuliaFEM Book" +subtitle: "A comprehensive manual mixing theory, software design, and personal experience" +description: "Deep dive into FEM theory, design philosophy, and research directions" +date: 2025-11-09 +author: "Jukka Aho" +categories: ["theory", "research", "philosophy"] +keywords: ["fem theory", "contact mechanics", "design philosophy", "research"] +audience: "researchers and theory enthusiasts" +level: "expert" +type: "book" +status: "work in progress" +--- + # The JuliaFEM Book **Audience:** Advanced researchers, theory nerds, those who want to understand the "why" and "how" at a deep level. And Jukka. diff --git a/docs/book/benchmarks/shape_function_derivatives_ad_vs_manual.md b/docs/book/benchmarks/shape_function_derivatives_ad_vs_manual.md index 2283c87..3baf323 100644 --- a/docs/book/benchmarks/shape_function_derivatives_ad_vs_manual.md +++ b/docs/book/benchmarks/shape_function_derivatives_ad_vs_manual.md @@ -1,3 +1,22 @@ +--- +title: "Shape Function Derivatives: Hand-Calculated vs Automatic Differentiation" +subtitle: "Performance benchmark for Tet10 element derivatives" +description: "Comprehensive benchmark showing 30× performance difference between manual and AD derivatives" +date: 2025-11-09 +author: "Jukka Aho" +categories: ["benchmarks", "performance", "research"] +keywords: ["automatic differentiation", "performance", "shape functions", "derivatives", "tensors.jl", "tet10"] +audience: "developers and researchers" +level: "advanced" +type: "benchmark" +series: "The JuliaFEM Book" +chapter: "Part IV: Research" +experiment_date: "2025-11-09" +tools: ["BenchmarkTools.jl", "Tensors.jl"] +status: "completed" +context: "Major zero-allocation refactoring (immutable Element, tuple-based APIs)" +--- + # Shape Function Derivatives: Hand-Calculated vs Automatic Differentiation **Date:** November 9, 2025 diff --git a/docs/book/lagrange_basis_functions.md b/docs/book/lagrange_basis_functions.md index e12e8ec..8a57e25 100644 --- a/docs/book/lagrange_basis_functions.md +++ b/docs/book/lagrange_basis_functions.md @@ -1,3 +1,20 @@ +--- +title: "Lagrange Basis Functions" +subtitle: "Mathematical foundations of finite element interpolation" +description: "Complete derivation of Lagrange basis functions using Vandermonde matrix method" +date: 2025-11-09 +author: "Jukka Aho" +categories: ["theory", "mathematics", "fem"] +keywords: ["lagrange basis", "shape functions", "interpolation", "vandermonde matrix", "fem theory"] +audience: "researchers and advanced users" +level: "expert" +type: "theory" +series: "The JuliaFEM Book" +chapter: "Part I: Foundations" +math: true +prerequisites: ["linear algebra", "numerical analysis", "fem basics"] +--- + # Lagrange Basis Functions in JuliaFEM **Date:** November 9, 2025 diff --git a/docs/contributor/README.md b/docs/contributor/README.md index e27e763..a21c2f2 100644 --- a/docs/contributor/README.md +++ b/docs/contributor/README.md @@ -1,3 +1,15 @@ +--- +title: "JuliaFEM Contributor Manual" +description: "Technical guide for developers and contributors" +date: 2025-11-09 +author: "Jukka Aho" +categories: ["development", "contributor guide"] +keywords: ["juliafem", "development", "architecture", "testing", "performance"] +audience: "developers" +level: "advanced" +type: "manual" +--- + # JuliaFEM Contributor Manual **Audience:** Developers, contributors, advanced users who want to extend or modify JuliaFEM. diff --git a/docs/contributor/status.md b/docs/contributor/status.md index d482fa5..c14765c 100644 --- a/docs/contributor/status.md +++ b/docs/contributor/status.md @@ -1,4 +1,18 @@ -# JuliaFEM Revival Status - November 8, 2025 +--- +title: "JuliaFEM Project Status" +description: "Current state of the revival project as of November 2025" +date: 2025-11-08 +updated: 2025-11-08 +author: "Jukka Aho" +categories: ["status", "progress"] +keywords: ["status", "progress", "revival", "roadmap"] +audience: "contributors" +level: "intermediate" +type: "status report" +series: "Contributor Manual" +--- + +# JuliaFEM Status ## ✅ SUCCESS: Package Loads! diff --git a/docs/contributor/test_fixes_needed.md b/docs/contributor/test_fixes_needed.md index 85c3fa0..421d417 100644 --- a/docs/contributor/test_fixes_needed.md +++ b/docs/contributor/test_fixes_needed.md @@ -1,3 +1,18 @@ +--- +title: "Test Fixes Needed" +description: "Known test failures and fixes required for full test suite passing" +date: 2025-11-09 +updated: 2025-11-09 +author: "Jukka Aho" +categories: ["testing", "todo"] +keywords: ["tests", "failures", "fixes", "todo"] +audience: "contributors" +level: "intermediate" +type: "technical note" +series: "Contributor Manual" +status: "active maintenance" +--- + # Test Fixes Needed **Date:** November 8, 2025 diff --git a/docs/contributor/testing_philosophy.md b/docs/contributor/testing_philosophy.md index 20f6d2b..2e756c3 100644 --- a/docs/contributor/testing_philosophy.md +++ b/docs/contributor/testing_philosophy.md @@ -1,4 +1,17 @@ -# JuliaFEM Testing Philosophy +--- +title: "Testing Philosophy" +description: "How and why we test in JuliaFEM" +date: 2025-11-08 +author: "Jukka Aho" +categories: ["testing", "quality assurance"] +keywords: ["testing", "unit tests", "verification", "validation"] +audience: "contributors" +level: "intermediate" +type: "guide" +series: "Contributor Manual" +--- + +# Testing Philosophy **Date:** November 9, 2025 **Goal:** 99% code coverage with educational, fast, well-structured tests diff --git a/docs/user/README.md b/docs/user/README.md index eca1274..db12394 100644 --- a/docs/user/README.md +++ b/docs/user/README.md @@ -1,3 +1,15 @@ +--- +title: "JuliaFEM User Manual" +description: "Quick start guide and practical tutorials for end users" +date: 2025-11-09 +author: "Jukka Aho" +categories: ["user guide", "tutorial"] +keywords: ["juliafem", "quick start", "tutorial", "examples"] +audience: "end users" +level: "beginner" +type: "manual" +--- + # JuliaFEM User Manual **Audience:** End users, engineers, students who want to run simulations and get results. diff --git a/scripts/README.md b/scripts/README.md index 41c50c1..beddd06 100644 --- a/scripts/README.md +++ b/scripts/README.md @@ -1,3 +1,15 @@ +--- +title: "JuliaFEM Scripts" +description: "Development and code generation scripts for JuliaFEM" +date: 2025-11-09 +author: "Jukka Aho" +categories: ["development", "tools", "automation"] +keywords: ["scripts", "code generation", "automation", "development tools"] +audience: "contributors" +level: "intermediate" +type: "technical documentation" +--- + # JuliaFEM Scripts This directory contains development and code generation scripts for JuliaFEM.