Skip to content

Commit c75bad3

Browse files
yannrichet-asnryannrichet-asnr
authored
Merge pull request #1 from Funz/copilot/build-documentation-website
Build comprehensive ReadTheDocs-like documentation website for FZ and plugins
2 parents ba154da + 74c71b0 commit c75bad3

42 files changed

Lines changed: 4146 additions & 1 deletion

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/deploy.yml‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
name: Deploy Documentation
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
pull_request:
8+
branches:
9+
- main
10+
workflow_dispatch:
11+
12+
permissions:
13+
contents: write
14+
pages: write
15+
id-token: write
16+
17+
jobs:
18+
deploy:
19+
runs-on: ubuntu-latest
20+
steps:
21+
- name: Checkout code
22+
uses: actions/checkout@v4
23+
24+
- name: Setup Python
25+
uses: actions/setup-python@v5
26+
with:
27+
python-version: '3.11'
28+
29+
- name: Install dependencies
30+
run: |
31+
pip install mkdocs mkdocs-material pymdown-extensions
32+
33+
- name: Build documentation
34+
run: |
35+
mkdocs build
36+
37+
- name: Deploy to GitHub Pages
38+
if: github.event_name == 'push' && github.ref == 'refs/heads/main'
39+
uses: peaceiris/actions-gh-pages@v3
40+
with:
41+
github_token: ${{ secrets.GITHUB_TOKEN }}
42+
publish_dir: ./site
43+
publish_branch: gh-pages

‎.gitignore‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# MkDocs build output
2+
site/
3+
4+
# Python
5+
__pycache__/
6+
*.py[cod]
7+
*$py.class
8+
*.so
9+
.Python
10+
env/
11+
venv/
12+
ENV/
13+
.venv
14+
15+
# IDE
16+
.vscode/
17+
.idea/
18+
*.swp
19+
*.swo
20+
*~
21+
22+
# OS
23+
.DS_Store
24+
Thumbs.db

‎README.md‎

Lines changed: 87 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,87 @@
1-
# fz.github.io
1+
# FZ Documentation Website
2+
3+
This repository hosts the documentation website for [FZ - Parametric Scientific Computing Framework](https://github.com/Funz/fz).
4+
5+
## 📚 Documentation Site
6+
7+
Visit the live documentation at: **https://funz.github.io**
8+
9+
## 🚀 Quick Links
10+
11+
- [Installation Guide](https://funz.github.io/getting-started/installation/)
12+
- [Quick Start](https://funz.github.io/getting-started/quickstart/)
13+
- [Core Functions](https://funz.github.io/user-guide/core-functions/fzr/)
14+
- [Plugins](https://funz.github.io/plugins/)
15+
- [Google Colab Notebooks](https://funz.github.io/examples/colab/)
16+
17+
## 📓 Google Colab Examples
18+
19+
Try FZ directly in your browser:
20+
21+
- [Perfect Gas Example](https://colab.research.google.com/github/Funz/fz.github.io/blob/main/notebooks/perfectgas_example.ipynb)
22+
- [OpenModelica Integration](https://colab.research.google.com/github/Funz/fz.github.io/blob/main/notebooks/modelica_example.ipynb)
23+
24+
## 🔌 FZ Plugins
25+
26+
- [FZ-Moret](https://github.com/Funz/fz-moret) - Moret model plugin
27+
- [FZ-MCNP](https://github.com/Funz/fz-mcnp) - Monte Carlo N-Particle Transport
28+
- [FZ-Cathare](https://github.com/Funz/fz-cathare) - Thermal-hydraulic system code
29+
- [FZ-Cristal](https://github.com/Funz/fz-cristal) - Cristal simulation plugin
30+
- [FZ-Scale](https://github.com/Funz/fz-scale) - Scale nuclear analysis code
31+
- [FZ-Telemac](https://github.com/Funz/fz-telemac) - Hydrodynamics simulation system
32+
33+
## 🛠️ Building the Documentation
34+
35+
This site is built with [MkDocs](https://www.mkdocs.org/) and the [Material theme](https://squidfunk.github.io/mkdocs-material/).
36+
37+
### Prerequisites
38+
39+
```bash
40+
pip install mkdocs mkdocs-material pymdown-extensions
41+
```
42+
43+
### Local Development
44+
45+
```bash
46+
# Clone the repository
47+
git clone https://github.com/Funz/fz.github.io.git
48+
cd fz.github.io
49+
50+
# Serve locally with live reload
51+
mkdocs serve
52+
53+
# Open http://127.0.0.1:8000 in your browser
54+
```
55+
56+
### Build
57+
58+
```bash
59+
# Build static site
60+
mkdocs build
61+
62+
# Output in site/ directory
63+
```
64+
65+
### Deploy
66+
67+
The documentation is automatically deployed to GitHub Pages when changes are pushed to the `main` branch via GitHub Actions.
68+
69+
## 📝 Contributing
70+
71+
Contributions to the documentation are welcome! Please:
72+
73+
1. Fork this repository
74+
2. Create a feature branch
75+
3. Make your changes
76+
4. Test locally with `mkdocs serve`
77+
5. Submit a pull request
78+
79+
### Adding Content
80+
81+
- Documentation pages are in `docs/`
82+
- Notebooks are in `notebooks/`
83+
- Configuration is in `mkdocs.yml`
84+
85+
## 📄 License
86+
87+
BSD 3-Clause License - see the [FZ repository](https://github.com/Funz/fz) for details.

‎SUMMARY.md‎

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
1+
# FZ Documentation Website - Summary
2+
3+
## What Was Built
4+
5+
A comprehensive ReadTheDocs-like documentation website for the FZ parametric scientific computing framework.
6+
7+
## Key Features
8+
9+
### 1. MkDocs with Material Theme
10+
- Professional, modern design
11+
- Responsive layout for all devices
12+
- Dark/light mode toggle
13+
- Advanced search functionality
14+
- Beautiful code highlighting
15+
16+
### 2. Comprehensive Documentation (34 Pages)
17+
18+
#### Getting Started
19+
- Installation guide (multiple methods, OS-specific)
20+
- Quick start with complete example
21+
- Core concepts and fundamentals
22+
23+
#### User Guide
24+
- Core functions: fzi, fzc, fzo, fzr
25+
- Model definition
26+
- Calculator types (shell, SSH, cache)
27+
- Advanced features (parallel, caching, formulas, interrupts)
28+
29+
#### Plugins (6 Plugins)
30+
- FZ-Moret - Moret model plugin
31+
- FZ-MCNP - Monte Carlo N-Particle Transport
32+
- FZ-Cathare - Thermal-hydraulic system code
33+
- FZ-Cristal - Cristal simulation plugin
34+
- FZ-Scale - Scale nuclear analysis code
35+
- FZ-Telemac - Hydrodynamics simulation system
36+
37+
#### Examples
38+
- Perfect Gas pressure study (complete)
39+
- Modelica/OpenModelica integration
40+
- Remote HPC execution
41+
- Google Colab notebooks
42+
43+
#### Reference
44+
- API reference
45+
- Configuration
46+
- Environment variables
47+
- Troubleshooting
48+
49+
### 3. Google Colab Notebooks (2 Notebooks)
50+
51+
1. **perfectgas_example.ipynb**
52+
- Basic parametric study
53+
- Ideal gas law calculations
54+
- Visualization with matplotlib
55+
- Ready to run in browser
56+
57+
2. **modelica_example.ipynb**
58+
- OpenModelica integration
59+
- Dynamic system simulations
60+
- Harmonic oscillator example
61+
- Parameter sweep and analysis
62+
63+
### 4. GitHub Pages Deployment
64+
65+
- Automated deployment with GitHub Actions
66+
- Builds on every push to main
67+
- Published to https://funz.github.io
68+
- Continuous integration/deployment
69+
70+
## File Structure
71+
72+
```
73+
fz.github.io/
74+
├── .github/
75+
│ └── workflows/
76+
│ └── deploy.yml # GitHub Actions deployment
77+
├── docs/ # Documentation source
78+
│ ├── index.md # Homepage
79+
│ ├── getting-started/ # 3 pages
80+
│ ├── user-guide/ # 12 pages
81+
│ ├── plugins/ # 7 pages
82+
│ ├── examples/ # 4 pages
83+
│ ├── reference/ # 4 pages
84+
│ └── contributing/ # 2 pages
85+
├── notebooks/ # Google Colab notebooks
86+
│ ├── perfectgas_example.ipynb
87+
│ └── modelica_example.ipynb
88+
├── mkdocs.yml # MkDocs configuration
89+
├── .gitignore # Git ignore rules
90+
└── README.md # Repository README
91+
```
92+
93+
## Technologies Used
94+
95+
- **MkDocs**: Static site generator for documentation
96+
- **Material for MkDocs**: Beautiful, responsive theme
97+
- **Python Markdown Extensions**: Enhanced markdown features
98+
- **GitHub Actions**: Automated deployment
99+
- **GitHub Pages**: Free hosting
100+
- **Jupyter Notebooks**: Interactive examples
101+
102+
## How to Use
103+
104+
### Local Development
105+
```bash
106+
pip install mkdocs mkdocs-material pymdown-extensions
107+
mkdocs serve
108+
# Open http://127.0.0.1:8000
109+
```
110+
111+
### Build
112+
```bash
113+
mkdocs build
114+
# Output in site/ directory
115+
```
116+
117+
### Deploy
118+
Automatically deployed via GitHub Actions when pushing to main branch.
119+
120+
## Success Metrics
121+
122+
✅ 34 documentation pages created
123+
✅ 2 Google Colab notebooks
124+
✅ All plugins documented
125+
✅ Complete examples with code
126+
✅ Professional design with Material theme
127+
✅ Automated deployment configured
128+
✅ Mobile-responsive
129+
✅ Search functionality
130+
✅ Dark/light mode
131+
132+
## Next Steps (Optional Future Enhancements)
133+
134+
- Add more Google Colab notebooks for each plugin
135+
- Create video tutorials
136+
- Add interactive examples
137+
- Expand API reference with auto-generated docs
138+
- Add versioning support
139+
- Create tutorials section
140+
- Add FAQ page
141+
142+
## Links
143+
144+
- **Repository**: https://github.com/Funz/fz.github.io
145+
- **Live Site**: https://funz.github.io (once deployed)
146+
- **Main FZ Repo**: https://github.com/Funz/fz
147+
148+
## Contact
149+
150+
For questions or contributions, please open an issue in the repository.

‎docs/contributing/development.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Development
2+
3+
Contributing to FZ. See the [main FZ documentation](https://github.com/Funz/fz#development) for complete details.

‎docs/contributing/testing.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Testing
2+
3+
Running FZ tests. See the [main FZ documentation](https://github.com/Funz/fz#running-tests) for complete details.

0 commit comments

Comments
 (0)