192 add and test tutorials in documentation

[JessieGould]

closes #192

[JessieGould]

"We should consider moving the current tutorials into the documentation, ..."
---- the calculations ones are now in docs with nbsphinx (ie not the workgraph ones )

"...and testing them. See stfc/janus-core#399."
---- troubleshooting / updating
---- tidying

" This may also include removing/reworking the current Usage and Tutorial sections. "
---- I have drafted a welcome page for docs / readme_tutorials for devs
---- think about logical order
---- include basic.ipynb from aiida

[JessieGould]

consider removing pandoc from toml? ie is it necessary

[Copilot]

Pull Request Overview

This PR adds tutorial notebooks to the documentation and configures the necessary tooling to render them. The main additions are four Jupyter notebook tutorials covering single point calculations, descriptors, geometry optimisation, and high-throughput screening.

• Adds nbsphinx and pandoc dependencies for rendering Jupyter notebooks in documentation
• Includes four comprehensive tutorial notebooks demonstrating various calculation types
• Updates function name from generate_node_graph to generate_provenance_graph in example code
• Fixes a duplicate word typo in developer documentation

Reviewed Changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
pyproject.toml	Adds nbsphinx and pandoc dependencies to docs dependency group
docs/source/conf.py	Configures nbsphinx extension with error allowance
docs/source/user_guide/index.rst	Adds four new notebook entries to user guide
docs/source/user_guide/notebooks/singlepoint.ipynb	New tutorial for single point calculations
docs/source/user_guide/notebooks/descriptors.ipynb	New tutorial for descriptor calculations
docs/source/user_guide/notebooks/geometry-optimisation.ipynb	New tutorial for geometry optimisation
docs/source/user_guide/notebooks/high-throughput-screening.ipynb	New tutorial for high-throughput screening
examples/tutorials/workgraphs/simple_workgraph.ipynb	Updates function name to generate_provenance_graph
docs/source/developer_guide/index.rst	Fixes duplicate word "individual"
.github/workflows/docs.yml	Adds pandoc installation step
.github/workflows/ci.yml	Adds pandoc installation step

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[JessieGould]

Issues:

• NameError: name 'PK' is not defined: Depending on how this compiles, could this be "1" or use "run_get_node" ?
• How to provide PK for other ones? - difficult to know without seeing it merged.
• Throughput: conf = JanusConfigfile(Path("config_sp.yaml").absolute()) : works locally but raises value error for local docs build (does not correspond to an existing file : shown when viewing docs through terminal firefox)
• throughput: AttributeError: exit_status (box 10)

These will display differently online as they do in a local build so its difficult to know what will need fixing / whether these would work.

[ElliottKasoar]

• NameError: name 'PK' is not defined: Depending on how this compiles, could this be "1" or use "run_get_node" ?
• How to provide PK for other ones? - difficult to know without seeing it merged.

We can probably get it programatically e.g. node.pk in cases where we've used run_get_node. We can still mention that you can get it by looking at verdi process list, but I don't think it should be necessary.

• Throughput: conf = JanusConfigfile(Path("config_sp.yaml").absolute()) : works locally but raises value error for local docs build (does not correspond to an existing file : shown when viewing docs through terminal firefox)
• throughput: AttributeError: exit_status (box 10)

We can use a path relative to the file that the notebook is in e.g. via pathlib.Path().resolve(). You should check how this behaves in different environments e.g. in Google Colab (just use one of the existing janus-core examples and see what it does).

If it works on linux (WSL), we can always describe any minor changes that are needed, or generally warn that the path may need correcting.

• throughput: AttributeError: exit_status (box 10)

What does this mean?

These will display differently online as they do in a local build so its difficult to know what will need fixing / whether these would work.

Do you mean local as in your version of the built documentation, or local as in your version of the notebook itself? If you're running in WSL and looking at the built docs, it shouldn't be too different, barring set-up differences.

If that's still a concern, you can temporarily get it to build on your fork instead, but that's a bit of a process (I'd probably do it on a new branch so it doesn't affect this PR, but you'd need to set up your fork permissions correctly, change the workflow to build on non-STFC repos, etc.)

[JessieGould]

the following changes have been made and should cover the above issues

1. removed all example calcs as they are repeated in docs
2. replaced "pk" or otherwise with output pointers
3. added structures and janusconfig to allow high throughput to run correctly
4. will not build docs if errors are thrown up

To consider:

• have added Aiida interal classes to nitpick_ignore in conf.py (This may be overkill, its a little outside of my knowledge base, it wont interfer with functionality it just suppresses the warnings for docs build?)
• Depending on how docs are used (ie they do not download the entire repo, just the tutorial notebook) it may be useful to provide a downloadable "structures" "janusconfig"
• some hyerlinks may not work?