Skip to content

📚 DOCS: Add new tutorial modules#7205

Open
GeigerJ2 wants to merge 39 commits into
aiidateam:mainfrom
GeigerJ2:docs/integrate-tutorials
Open

📚 DOCS: Add new tutorial modules#7205
GeigerJ2 wants to merge 39 commits into
aiidateam:mainfrom
GeigerJ2:docs/integrate-tutorials

Conversation

@GeigerJ2
Copy link
Copy Markdown
Collaborator

@GeigerJ2 GeigerJ2 commented Feb 6, 2026 •
edited
Loading

Rendered view here:
https://aiida--7205.org.readthedocs.build/projects/aiida-core/en/7205/tutorials/index.html

Warning

If RTD build in CI failed, the rendered view I link here is outdated!!

The important source files to review are: docs/source/tutorials/module*.md

@codecov
Copy link
Copy Markdown

codecov Bot commented Feb 6, 2026 •
edited
Loading

Codecov Report

❌ Patch coverage is 0% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 80.28%. Comparing base (2068a7d) to head (13f25e1).

Files with missing lines Patch % Lines
src/aiida/tools/ipython/ipython_magics.py 0.00% 2 Missing ⚠️
Additional details and impacted files 
@@            Coverage Diff             @@
##             main    #7205      +/-   ##
==========================================
- Coverage   80.28%   80.28%   -0.00%     
==========================================
  Files         577      577              
  Lines       45545    45547       +2     
==========================================
+ Hits        36562    36563       +1     
- Misses       8983     8984       +1

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@GeigerJ2 GeigerJ2 force-pushed the docs/integrate-tutorials branch from dcfd575 to 6a52d64 Compare April 8, 2026 09:08
GeigerJ2 added 24 commits April 9, 2026 07:15
@GeigerJ2
first claude vibe-coded infrastructure
e70a37b
@GeigerJ2
fix daemon stop
7a933fb
@GeigerJ2
fix ci
ea3cef8
@GeigerJ2
fix ci
9e71e5d
@GeigerJ2
strip down to skeletons, see if CI passes
91db7a3
@GeigerJ2
try ci
41d0893
@GeigerJ2
module 1; try via CI
fd9c2e8
@GeigerJ2
ci
1f0e89a
@GeigerJ2
use persistent profile
17dd49b
@GeigerJ2
ci
8c8bbb5
@GeigerJ2
refs
9c283c5
@GeigerJ2
module 2
8480a33
@GeigerJ2
fix rtd build
a6b45cc
@GeigerJ2
Improve tutorial modules 1 & 2
f9cd760 
CalcJob concepts, static script, cleaner UX

Intro:
- Add teaser section heading with TODO checklist for showcasing key
  features (WorkGraph, error handling, querying, visualization)
- Fix module count: six → seven

Module 1:
- Add tip about `verdi node graph generate <PK>` CLI alternative

Module 2:
- Introduce CalcJob concept properly before first use, explain
  difference to calcfunction, link to topics/how-to docs
- Reference static script file (gp/reaction-diffusion.py) via
  literalinclude + dropdown instead of writing 100-line script
  on-the-fly
- Make work_dir creation visible (was hidden as tutorial_dir)
- Access output via node.outputs (AiiDA pattern) instead of results dict
- Hide parser function cell (hide-cell tag)
- Fix failure demo: remove outputs/parser from failing run so
  aiida-shell surfaces the actual non-zero exit status instead of
  misleading 303
- Put load_profile instructions in proper code block
- Suppress write_text() return value ("80") with semicolons
- Rephrase Computer/Code section to acknowledge verdi presto
- Add cross-references to topics:calculations, how-to:run-codes,
  how-to:plugin-codes throughout
- Update learning objectives and summary to match actual content
@GeigerJ2
Extract tutorial code to typed standalone files
c3d3c7e 
Move inline code snippets (simulation script, parser, plotting) from
markdown code cells to standalone `.py` files under `include/`. This
enables LSP support (type checking, autocomplete) for tutorial code and
uses `{literalinclude}` + `{dropdown}` for display, `%run -i` for
notebook execution.

All three files pass mypy --strict, and ruff:

Also updates module1.md to use `%run -i include/plot_fields.py` instead
of inline matplotlib code.
@GeigerJ2
Add teaser page, downloadable notebooks, convert index to MyST
442f7b1 
Tutorials infrastructure:
- Add `_ext/inline_downloads.py` Sphinx extension that post-processes
  downloaded notebooks: inlines `%run -i` files, converts MyST
  admonitions to HTML alert divs, dropdowns to `<details>`,
  literalinclude to code blocks, and strips MyST-only roles/labels —
  making notebooks fully self-contained and Jupyter-compatible
- Add `{nb-download}` links to module1 and module2 for one-click
  download
- Register extension in conf.py

Content:
- Add `teaser.md`: user-focused preview of AiiDA capabilities
  (monitoring, error recovery, querying, provenance, sharing, workflow
  extensibility)
- Convert `index.rst` → `index.md` (MyST); separate "AiiDA in Action"
  card above the module grid; update redirects.txt accordingly
- Generalize example-specific language in headings, learning objectives,
  and module tables across intro.md, module3.md, and module6.md

Tutorial code cleanup:
- Extract inline `simulate()` from module1.md to typed
  `include/simulate.py` with `SimParams(TypedDict)`, loaded via `%run
  -i`
- Extract provenance graph boilerplate to `include/plot_provenance.py`
- Add IPython magic commands note in module1.md explaining `%run -i`,
  `%verdi`, and `%load_ext aiida`
- Pre-register `InstalledCode('python3')` in module2.md hidden cell so
  `verdi process list` shows `python3@localhost` instead of full venv
  path
@GeigerJ2
add sphinx ext for downloads as ipynb
e039ef5
@GeigerJ2
add temporary notes in _notes/
bef6dfb
@GeigerJ2
add updated modules with admonitions
7b727ee
@GeigerJ2
add more admonitions
ab89380
@GeigerJ2
create localhost also in module2
2ba5a01
@GeigerJ2
centralized setup script
40b0da9
@GeigerJ2
re-organize after meeting
8c236e1
@GeigerJ2
fix input file location for ci build
8f4c347
@GeigerJ2 GeigerJ2 removed the request for review from danielhollas April 9, 2026 08:50
@GeigerJ2 GeigerJ2 mentioned this pull request Apr 10, 2026
Closed
mbercx
mbercx reviewed Apr 13, 2026
View reviewed changes
Comment thread docs/source/tutorials/module0.md Outdated
mbercx
mbercx reviewed Apr 13, 2026
View reviewed changes
Comment thread docs/source/tutorials/module0.md Outdated
mbercx
mbercx reviewed Apr 13, 2026
View reviewed changes
Comment thread docs/source/tutorials/module0.md Outdated
mbercx
mbercx reviewed Apr 13, 2026
View reviewed changes
Comment thread docs/source/tutorials/module0.md Outdated
mbercx
mbercx reviewed Apr 13, 2026
View reviewed changes
Comment thread docs/source/tutorials/module0.md Outdated
mbercx
mbercx reviewed Apr 13, 2026
View reviewed changes
Comment thread docs/source/tutorials/module0.md Outdated
print(f"Fields shape: {data['U_final'].shape}")
```

## Visualizing the results
Copy link
Copy Markdown
Member

@mbercx mbercx Apr 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

THIS! Show this at the top (but maybe smaller, i.e. a diagram, like):

Image

And a very easy, intuitive explanation of what I'm looking at. I have no idea at the moment, to be honest. Maybe I didn't read the content properly, but neither will users.

Copy link
Copy Markdown
Member

@mbercx mbercx Apr 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As a side note: less inputs. Make some a default (probably seed?) Unless the are necessary for later (randomization?). Anyways, make the input file as small as possible for our needs.

Copy link
Copy Markdown
Member

@mbercx mbercx Apr 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also, maybe merge this section with the part that shows the results from the last one?

So we have

  • Running the simulation
  • Results
  • ...

Copy link
Copy Markdown
Collaborator Author

@GeigerJ2 GeigerJ2 Apr 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done! Added a static image of the UV fields right at the top of the module (below the intro text), so readers immediately see what the simulation produces. Merged the "Visualizing the results" section into "Running the simulation" (no separate heading). Removed Fields shape output. Re: reducing inputs, seed is already optional in the script (defaults to None), so the input file could drop it. Will revisit when simplifying further. Input file is anyway not shown atm. Could not be bothered to leave my beautiful terminal yet, to create a such a scheme, as you suggest, but we can do it when we also create the package!

mbercx
mbercx reviewed Apr 13, 2026
View reviewed changes
Comment thread docs/source/tutorials/module0.md Outdated
mbercx
mbercx reviewed Apr 13, 2026
View reviewed changes
Comment thread docs/source/tutorials/module0.md Outdated
mbercx
mbercx reviewed Apr 13, 2026
View reviewed changes
Comment thread docs/source/tutorials/module0.md Outdated
mbercx
mbercx reviewed Apr 13, 2026
View reviewed changes
Comment thread docs/source/tutorials/module0.md Outdated
mbercx
mbercx reviewed Apr 13, 2026
View reviewed changes
Comment thread docs/source/tutorials/module0.md Outdated
mbercx
mbercx reviewed Apr 13, 2026
View reviewed changes
Comment thread docs/source/tutorials/module0.md Outdated
mbercx
mbercx reviewed Apr 13, 2026
View reviewed changes
Comment thread docs/source/tutorials/module0.md Outdated
mbercx
mbercx reviewed Apr 13, 2026
View reviewed changes
Comment thread docs/source/tutorials/module0.md Outdated
mbercx
mbercx reviewed Apr 13, 2026
View reviewed changes
Comment thread docs/source/tutorials/module0.md Outdated
mbercx
mbercx reviewed Apr 13, 2026
View reviewed changes
Comment thread docs/source/tutorials/module0.md Outdated
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@mbercx mbercx mbercx left review comments

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

None yet

Projects

aiida-core v2.9.0
Status: Todo

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@GeigerJ2 @mbercx
⚡