Skip to content

Commit c4729e9

Browse files
JFRudzinskiEBB2675
JFRudzinski
and
EBB2675
authored
minimal auto schema docs generation (#267)
* minimal auto schema docs generation * fixed jinja template formatting * template for overview page * mermaid to png, click-zoom images, full pipeline script, fix metainfo links * switch to svg for mermaid * simplify mermaids * record of changes * add doc dep's to toml * rename auto section * new verticals corresponding to root * simple formatting * add inheritance to diagrams, better organization * new verticals, new logic for filtering in diagrams, auto docs generation dev docs * more rules, new model system * add doc strings * improve doc string format * prevent overflow in docstring tables with admonitions * shrink small diagrams * simplify diagrams * nested navigation * implement panzoom with mermaid * improve panzoom * restore src edits * ruff * ruff upgrade * full verticle refactoring after rebase * refactor explanation section * ruff * Update requirements_docs.txt Co-authored-by: Esma B. Boydas <80156958+EBB2675@users.noreply.github.com> * remove out of scope, improve legend * remove PP ref, and end section of overview page --------- Co-authored-by: Esma B. Boydas <80156958+EBB2675@users.noreply.github.com>
1 parent c74a0b5 commit c4729e9

File tree

80 files changed

+8245
-52
lines changed

Some content is hidden

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

80 files changed

+8245
-52
lines changed

‎README.md‎

Lines changed: 91 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -120,16 +120,28 @@ The settings configuration file `.vscode/settings.json` automatically applies th
120120

121121
### Documentation on Github pages
122122

123-
To view the documentation locally, install the related packages using:
123+
To view the documentation locally, install the documentation dependencies:
124124
```sh
125-
uv pip install -r requirements_docs.txt
125+
uv pip install -e '.[docs]'
126126
```
127127

128+
**Note**: The documentation pipeline uses `npx` (Node Package Runner) to convert Mermaid diagrams to PNG images for better zoom functionality. Make sure you have Node.js/npm installed:
129+
```sh
130+
which npx # Check if npx is available
131+
```
132+
133+
If not installed, download Node.js from https://nodejs.org/
134+
128135
Run the documentation server:
129136
```sh
130137
mkdocs serve
131138
```
132139

140+
Alternatively, you can run mkdocs directly with `uv run` without installing the dependencies:
141+
```sh
142+
uv run --extra docs mkdocs serve
143+
```
144+
133145

134146
## Adding this plugin to NOMAD
135147

@@ -179,3 +191,80 @@ Pizarro, J.M., Boydas, E.B., Daelman, N., Ladines, A.N., Mohr, B. & Rudzinski, J
179191
| Dr. José M. Pizarro | [jose.pizarro@physik.hu-berlin.de](mailto:jose.pizarro@physik.hu-berlin.de) | GW, DMFT, BSE | [@JosePizarro3](https://github.com/JosePizarro3) |
180192
| Dr. Esma B. Boydas | [esma.boydas@physik.hu-berlin.de](mailto:esma.boydas@physik.hu-berlin.de) | Quantum Chemistry | [@EBB2675](https://github.com/EBB2675) |
181193
| Dr. Joseph F. Rudzinski (**Coordinator**) | [joseph.rudzinski@physik.hu-berlin.de](mailto:joseph.rudzinski@physik.hu-berlin.de) | General | [@JFRudzinski](https://github.com/JFRudzinski) |
194+
195+
196+
197+
## 🧩 Updating the Auto-Generated Schema Docs
198+
199+
The schema documentation is generated directly from the NOMAD-Simulations
200+
plugin source. Until CI automation is configured, you can update the pages
201+
manually using the helper scripts in `scripts/`.
202+
203+
### Prerequisites
204+
205+
**Node.js/npm Required**: The documentation pipeline uses `npx` to convert Mermaid diagrams to clickable, zoomable PNG images. Install Node.js from https://nodejs.org/ if you don't have it already.
206+
207+
### Quick Start: Generate Complete Documentation
208+
209+
Run the complete documentation pipeline with a single command:
210+
```bash
211+
python scripts/generate_docs_pipeline.py
212+
```
213+
214+
This automated pipeline will:
215+
1. Generate standalone diagram pages with Mermaid code
216+
2. Generate vertical schema documentation pages
217+
3. Generate the overview index page with all sections
218+
4. Convert all Mermaid diagrams to high-resolution PNG images
219+
5. Replace Mermaid code blocks with clickable zoom images
220+
221+
The result is a fully interactive documentation site with diagrams that can be clicked to zoom 2x.
222+
223+
### Manual Steps (Advanced)
224+
225+
If you prefer to run individual steps:
226+
227+
#### 1. Regenerate diagrams
228+
From the repository root:
229+
```bash
230+
python scripts/gen_diagrams.py
231+
```
232+
233+
This generates standalone diagram pages (e.g., `methods.diagram.md`) with:
234+
- Full-page Mermaid diagrams for better viewing/zooming
235+
- Legend explaining relationship types
236+
- Navigation back to the main vertical page
237+
238+
#### 2. Regenerate the schema docs
239+
240+
```bash
241+
python scripts/gen_docs.py \
242+
--pkg nomad_simulations \
243+
--module-prefix nomad_simulations \
244+
--templates-dir templates \
245+
--out-dir docs/schema
246+
```
247+
248+
This will generate:
249+
- An overview page (`docs/schema/index.md`) with links to all vertical domains
250+
- Individual vertical pages (e.g., `methods.md`, `basis.md`) with:
251+
- Purpose and scope descriptions
252+
- Mermaid relationship diagrams
253+
- Detailed section tables with class descriptions extracted from docstrings
254+
- Example YAML snippets for each section
255+
256+
#### 3. Convert diagrams to PNG (for click-zoom functionality)
257+
258+
```bash
259+
python scripts/mermaid_to_png.py
260+
```
261+
262+
This converts all Mermaid diagrams to high-resolution PNG images with click-to-zoom wrappers.
263+
264+
### Interactive Diagram Features
265+
266+
All generated diagrams support:
267+
- **Click to zoom** - Click any diagram to enlarge it 2x
268+
- **Click again to reset** - Click the zoomed diagram to return to normal size
269+
- **High resolution** - PNG images are generated at 2000px width with 2x scaling
270+
- **Transparent backgrounds** - Diagrams blend seamlessly with your theme

‎docs/assets/click-zoom.js‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
/**
2+
* Click-to-zoom functionality for diagram images
3+
*/
4+
document.addEventListener('DOMContentLoaded', function() {
5+
// Function to add click handlers to diagram images
6+
function setupClickZoom() {
7+
const images = document.querySelectorAll('.click-zoom-img');
8+
9+
images.forEach(function(img) {
10+
// Remove any existing click handler
11+
img.removeEventListener('click', toggleZoom);
12+
// Add click handler
13+
img.addEventListener('click', toggleZoom);
14+
});
15+
}
16+
17+
function toggleZoom(event) {
18+
event.preventDefault();
19+
this.classList.toggle('zoomed');
20+
}
21+
22+
// Initial setup
23+
setupClickZoom();
24+
25+
// Re-setup when navigation occurs (for Material's instant navigation)
26+
document.addEventListener('DOMContentLoaded', setupClickZoom);
27+
28+
// Also handle Material for MkDocs instant navigation
29+
if (typeof document$ !== 'undefined') {
30+
document$.subscribe(setupClickZoom);
31+
}
32+
});

‎docs/assets/mermaid-click-zoom.js‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
// Simple click-to-zoom for Mermaid diagrams
2+
// Based on the approach from fairmat-tutorial-14-computational-plugins
3+
4+
document.addEventListener('DOMContentLoaded', function() {
5+
// Wait for Mermaid to render, then wrap diagrams
6+
setTimeout(function() {
7+
wrapMermaidDiagrams();
8+
}, 500);
9+
10+
// Re-initialize on navigation (Material for MkDocs instant loading)
11+
if (typeof document$ !== 'undefined') {
12+
document$.subscribe(function() {
13+
setTimeout(wrapMermaidDiagrams, 500);
14+
});
15+
}
16+
});
17+
18+
function wrapMermaidDiagrams() {
19+
// Find all pre.mermaid elements
20+
const mermaidBlocks = document.querySelectorAll('pre.mermaid');
21+
22+
mermaidBlocks.forEach(function(pre) {
23+
// Skip if already wrapped
24+
if (pre.closest('.click-zoom')) {
25+
return;
26+
}
27+
28+
// Check if it has SVG (Mermaid has rendered)
29+
const svg = pre.querySelector('svg');
30+
if (!svg) {
31+
return;
32+
}
33+
34+
// Create the click-zoom wrapper structure
35+
const wrapper = document.createElement('div');
36+
wrapper.className = 'click-zoom';
37+
38+
const label = document.createElement('label');
39+
40+
const checkbox = document.createElement('input');
41+
checkbox.type = 'checkbox';
42+
43+
// Extract and clone the SVG
44+
const svgClone = svg.cloneNode(true);
45+
46+
// Build structure: wrapper > label > (checkbox + svg)
47+
label.appendChild(checkbox);
48+
label.appendChild(svgClone);
49+
wrapper.appendChild(label);
50+
51+
// Replace the pre element with our wrapper
52+
pre.parentNode.replaceChild(wrapper, pre);
53+
});
54+
}
55+

‎docs/assets/svg-pan-zoom-diagram.js‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
/**
2+
* Interactive SVG Pan/Zoom for Diagrams
3+
* Uses svg-pan-zoom library for smooth pan and zoom interactions
4+
*/
5+
6+
document.addEventListener('DOMContentLoaded', function() {
7+
// Function to initialize SVG pan/zoom on all diagram SVGs
8+
function initSvgPanZoom() {
9+
// Check if svg-pan-zoom library is loaded
10+
if (typeof svgPanZoom === 'undefined') {
11+
console.warn('svg-pan-zoom library not loaded');
12+
return;
13+
}
14+
15+
const svgEmbeds = document.querySelectorAll('.interactive-svg');
16+
17+
svgEmbeds.forEach(function(embedElement) {
18+
// Skip if already initialized
19+
if (embedElement.svgPanZoomInstance) return;
20+
21+
// Wait for embed to load
22+
embedElement.addEventListener('load', function() {
23+
try {
24+
// Get the SVG document from embed
25+
const svgDoc = embedElement.getSVGDocument ? embedElement.getSVGDocument() :
26+
embedElement.contentDocument;
27+
28+
if (!svgDoc) {
29+
console.warn('Could not access SVG document');
30+
return;
31+
}
32+
33+
const svg = svgDoc.querySelector('svg') || svgDoc.documentElement;
34+
if (!svg) {
35+
console.warn('SVG element not found');
36+
return;
37+
}
38+
39+
// Initialize svg-pan-zoom
40+
const panZoomInstance = svgPanZoom(svg, {
41+
zoomEnabled: true,
42+
controlIconsEnabled: true,
43+
fit: true,
44+
center: true,
45+
minZoom: 0.5,
46+
maxZoom: 10,
47+
zoomScaleSensitivity: 0.3,
48+
dblClickZoomEnabled: true,
49+
mouseWheelZoomEnabled: true,
50+
preventMouseEventsDefault: true,
51+
});
52+
53+
// Store instance for potential later use
54+
embedElement.svgPanZoomInstance = panZoomInstance;
55+
56+
// Mark container as interacted on first pan/zoom
57+
const container = embedElement.closest('.diagram-container');
58+
if (container) {
59+
svg.addEventListener('mousedown', function() {
60+
container.classList.add('interacted');
61+
}, { once: true });
62+
}
63+
64+
console.log('SVG pan/zoom initialized for:', container ? container.dataset.diagram : 'diagram');
65+
66+
} catch (e) {
67+
console.error('Error initializing SVG pan/zoom:', e);
68+
}
69+
});
70+
71+
// Trigger load if already loaded
72+
if (embedElement.getSVGDocument || embedElement.contentDocument) {
73+
embedElement.dispatchEvent(new Event('load'));
74+
}
75+
});
76+
}
77+
78+
// Initial setup
79+
setTimeout(initSvgPanZoom, 100);
80+
81+
// Re-initialize on Material for MkDocs instant navigation
82+
if (typeof document$ !== 'undefined') {
83+
document$.subscribe(function() {
84+
setTimeout(initSvgPanZoom, 200);
85+
});
86+
}
87+
});

‎docs/contact.md‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,12 +8,15 @@ You can reach us by different channels. You can send as directly an email to the
88
|------|------------|--------|-----------------|
99
| Dr. Nathan Daelman | [nathan.daelman@physik.hu-berlin.de](mailto:nathan.daelman@physik.hu-berlin.de) | DFT, Precision | [@ndaelman-hu](https://github.com/ndaelman-hu) |
1010
| Dr. Bernadette Mohr | [mohrbern@physik.hu-berlin.de](mailto:mohrbern@physik.hu-berlin.de) | MD, FF | [@Bernadette-Mohr](https://github.com/Bernadette-Mohr) |
11-
| Dr. José M. Pizarro | [jose.pizarro@physik.hu-berlin.de](mailto:jose.pizarro@physik.hu-berlin.de) | GW, DMFT, BSE | [@JosePizarro3](https://github.com/JosePizarro3) |
11+
| Dr. Esma B. Boydas | [esma.boydas@physik.hu-berlin.de](mailto:esma.boydas@physik.hu-berlin.de) | Quantum Chemistry | [@EBB2675](https://github.com/EBB2675) |
1212
| Dr. Joseph F. Rudzinski (**Coordinator**) | [joseph.rudzinski@physik.hu-berlin.de](mailto:joseph.rudzinski@physik.hu-berlin.de) | General | [@JFRudzinski](https://github.com/JFRudzinski) |
1313

1414

1515
Alternatively, you can also:
1616

1717
- Open an [**issue**](https://github.com/fairmat-nfdi/nomad-simulations/issues) in the [Github project](https://github.com/fairmat-nfdi/nomad-simulations/), and tag any of us.
18-
- Join the [Discord channel](https://discord.gg/Gyzx3ukUw8) and ask us there directly.
19-
- If you are included as a contributor in the Github project, you can open new [**discussions**](https://github.com/fairmat-nfdi/nomad-simulations/discussions) regarding a new data schema or modelling you want to see covered.
18+
- Join the [NOMAD Discord server](https://discord.gg/Gyzx3ukUw8) and ask us there directly.
19+
20+
## Citation
21+
22+
Pizarro, J.M., Boydas, E.B., Daelman, N., Ladines, A.N., Mohr, B. & Rudzinski, J.F., NOMAD Simulations [Computer software]. https://zenodo.org/doi/10.5281/zenodo.13838811

docs/data_types.md renamed to docs/explanation/data_types.md

File renamed without changes.

docs/general.md renamed to docs/explanation/general.md

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ The `Simulation` section inherits from a _base section_ `BaseSimulation`. In NOM
1010
<div class="click-zoom">
1111
<label>
1212
<input type="checkbox">
13-
<img src="../assets/simulation_base.png" alt="Simulation base section diagram." width="80%" title="Click to zoom in">
13+
<img src="../../assets/simulation_base.png" alt="Simulation base section diagram." width="80%" title="Click to zoom in">
1414
</label>
1515
</div>
1616

@@ -19,7 +19,7 @@ The `Simulation` section inherits from a _base section_ `BaseSimulation`. In NOM
1919
<div class="click-zoom">
2020
<label>
2121
<input type="checkbox">
22-
<img src="../assets/simulation.png" alt="Simulation quantities and functions UML diagram." width="50%" title="Click to zoom in">
22+
<img src="../../assets/simulation.png" alt="Simulation quantities and functions UML diagram." width="50%" title="Click to zoom in">
2323
</label>
2424
</div>
2525

@@ -56,7 +56,7 @@ The following schematic represents a simplified representation of the `Simulatio
5656
<div class="click-zoom">
5757
<label>
5858
<input type="checkbox">
59-
<img src="../assets/simulation_composition.png" alt="Simulation composition diagram." width="90%" title="Click to zoom in">
59+
<img src="../../assets/simulation_composition.png" alt="Simulation composition diagram." width="90%" title="Click to zoom in">
6060
</label>
6161
</div>
6262

@@ -67,7 +67,7 @@ The `Program` base section contains all the information about the program / soft
6767
<div class="click-zoom">
6868
<label>
6969
<input type="checkbox">
70-
<img src="../assets/program.png" alt="Program quantities and functions UML diagram." width="75%" title="Click to zoom in">
70+
<img src="../../assets/program.png" alt="Program quantities and functions UML diagram." width="75%" title="Click to zoom in">
7171
</label>
7272
</div>
7373

docs/model_method/basis_sets.md renamed to docs/explanation/model_method/basis_sets.md

File renamed without changes.

docs/atoms_state/electronic_states.md renamed to docs/explanation/model_system/electronic_states.md

File renamed without changes.

docs/model_system/model_system.md renamed to docs/explanation/model_system/model_system.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,7 @@ for symbol in ['Si', 'Si']:
4646
model_system.particle_states.append(atom)
4747
```
4848

49-
Each `AtomsState` can include electronic structure information through the `electronic_state` field. See [Electronic States](../atoms_state/electronic_states.md) for details on describing electronic configurations.
49+
Each `AtomsState` can include electronic structure information through the `electronic_state` field. See [Electronic States](electronic_states.md) for details on describing electronic configurations.
5050

5151
### Alternative Representations
5252

@@ -244,6 +244,6 @@ interface.sub_systems.append(material_B)
244244
## See Also
245245

246246
- [Representation Architecture](representation.md): Detailed documentation of the geometric representation design
247-
- [Electronic States](../atoms_state/electronic_states.md): How to describe electronic configurations of atoms
247+
- [Electronic States](electronic_states.md): How to describe electronic configurations of atoms
248248
- [Normalization](../normalize.md): Overview of the normalization system
249249
- [General Schema Overview](../general.md): Introduction to the NOMAD simulations schema package

0 commit comments

Comments
 (0)