Build comprehensive ReadTheDocs-like documentation website for FZ and plugins

[Copilot]

Overview

This PR implements a complete documentation website for the FZ parametric scientific computing framework and its plugins, addressing the requirement to build a ReadTheDocs-like website to document https://github.com/Funz/fz and its plugins.

What's New

📚 Documentation Website

Built a professional documentation site using MkDocs with Material theme featuring:

• 34 comprehensive documentation pages covering all aspects of FZ
• Beautiful, responsive design with dark/light mode toggle
• Advanced search functionality for easy navigation
• Mobile-friendly layout accessible on all devices

📖 Content Structure

Getting Started

• Installation Guide: Multiple installation methods (source, PyPI, virtual env, Docker), OS-specific instructions, plugin installation
• Quick Start: Complete working example with the ideal gas law, step-by-step tutorial
• Core Concepts: Fundamental FZ concepts including variables, parametric studies, formulas, models, calculators, and caching

User Guide

• Core Functions: Detailed documentation for fzi (parse input), fzc (compile), fzo (parse output), and fzr (run study)
• Model Definition: How to define and use models
• Calculators: Local shell, SSH remote, and cache calculator documentation
• Advanced Features: Parallel execution, caching strategies, interrupt handling, formula evaluation

Plugin Documentation

Comprehensive documentation for all 6 FZ plugins:

• FZ-Moret - Moret model plugin
• FZ-MCNP - Monte Carlo N-Particle Transport Code
• FZ-Cathare - CATHARE thermal-hydraulic system code
• FZ-Cristal - Cristal simulation plugin
• FZ-Scale - SCALE nuclear analysis code system
• FZ-Telemac - TELEMAC-MASCARET hydrodynamics suite

Each plugin page includes installation instructions, use cases, and repository links.

Examples & Tutorials

• Perfect Gas Example: Complete parametric study with the ideal gas law, including visualization and analysis
• Modelica/OpenModelica Integration: Dynamic system simulations guide
• Remote HPC Execution: Running FZ on HPC clusters
• Google Colab Integration: Browser-based examples

📓 Google Colab Notebooks

Created 2 ready-to-run Jupyter notebooks for Google Colab:

1. perfectgas_example.ipynb

   • Basic parametric study using the ideal gas law
   • Complete workflow from installation to visualization
   • Interactive plots with matplotlib
   • No local installation required

2. modelica_example.ipynb

   • OpenModelica integration for dynamic systems
   • Harmonic oscillator parametric study
   • Damping and frequency parameter sweep
   • Heatmap visualization of results

Both notebooks include complete working examples with OpenModelica and other opensource simulation tools available in Colab.

🚀 Deployment Setup

• GitHub Actions workflow (.github/workflows/deploy.yml) for automated deployment
• Automatically builds and deploys to GitHub Pages on push to main
• Site will be accessible at https://funz.github.io

📸 Website Preview

The homepage features:

• Clear overview of FZ capabilities
• Quick navigation to all sections
• Links to plugins and examples
• Google Colab integration badges
• Professional Material Design theme

Technical Details

Technologies Used

• MkDocs 1.6.1: Static site generator
• Material for MkDocs 9.6.21: Professional theme
• PyMdown Extensions 10.16.1: Enhanced markdown features
• GitHub Actions: CI/CD pipeline
• GitHub Pages: Free hosting

File Structure

fz.github.io/
├── .github/workflows/deploy.yml    # Automated deployment
├── docs/                            # Documentation source (34 pages)
│   ├── index.md                    # Homepage
│   ├── getting-started/            # 3 pages
│   ├── user-guide/                 # 12 pages
│   ├── plugins/                    # 7 pages
│   ├── examples/                   # 4 pages
│   ├── reference/                  # 4 pages
│   └── contributing/               # 2 pages
├── notebooks/                       # Google Colab notebooks
│   ├── perfectgas_example.ipynb
│   └── modelica_example.ipynb
├── mkdocs.yml                      # MkDocs configuration
├── .gitignore                      # Exclude build artifacts
└── README.md                       # Updated with project info

How to Use

Local Development

pip install mkdocs mkdocs-material pymdown-extensions
mkdocs serve
# Open http://127.0.0.1:8000

Building

mkdocs build
# Output in site/ directory

Deployment

Automatically deployed via GitHub Actions when changes are pushed to main branch.

Benefits

✅ Comprehensive documentation split and enriched from the main FZ README
✅ All 6 plugins documented with installation and usage guides
✅ Google Colab integration with 2 complete notebooks
✅ OpenModelica examples and other opensource simulation tools
✅ Professional design with search and navigation
✅ Automated deployment with GitHub Actions
✅ Mobile responsive for access anywhere

Next Steps

Once merged to main:

1. GitHub Actions will automatically build and deploy the site
2. Documentation will be live at https://funz.github.io
3. Users can browse guides, try Colab notebooks, and explore plugins
4. Future updates can be made by simply editing markdown files

The documentation provides a complete resource for FZ users, from beginners to advanced users, with easy access to all plugins and ready-to-run examples.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• https://api.github.com/orgs/Funz/repos
  • Triggering command: curl -s REDACTED (http block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

Build a readthedocs-like website, to document https://github.com/Funz/fz and its plugins https://github.com/Funz/fz-*

The file https://github.com/Funz/fz/blob/main/README.md may contains most of information, but split this content and enrich it.
Also add some google colab notebooks and shortcuts for complete examples, including plugins for opensource simulations, available to install in colab (for instance modelica)

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.