Skip to content

Reorganized example/tutorial files#854

Merged
PicoCentauri merged 7 commits intomainfrom
doc-restructure
Oct 27, 2025
Merged

Reorganized example/tutorial files#854
PicoCentauri merged 7 commits intomainfrom
doc-restructure

Conversation

@PicoCentauri
Copy link
Contributor

@PicoCentauri PicoCentauri commented Oct 22, 2025

All files that are supposed to be rendered as tutorials are now in the examples subfolder in the root of the repo. Before, they were all over the place, and we handpicked them... The examples directory now contains two subfolders: 0-beginner and 1-advanced. Each of them has the tutorials sorted as before. They will be rendered as a nice gallery:

Screenshot 2025-10-22 at 15: 42: 41

The cleaned structure makes it easier to add new tutorials as no per-hand additions to various other files in the doc directory are necessary. Sphinx gallery will detect and render them if they are in one of the two subfolders.

I also generalised the running of the bash scripts when rendering the docs with tox. Now all .sh files in the examples directory will be run and verified. Also most of the training runs will be now called with subprocess in each script. This should use caching and speed up when working in the docs. Related to #797

Finally, @HannaTuerk suggested renaming the examples folder in docs/src to rendered_examples.

TODO

  • There are still some warnings I have to fix...

Maintainer/Reviewer checklist

  • CHANGELOG updated with public API or any other important changes?
  • GPU tests passed (maintainer comment: "cscs-ci run")?

📚 Documentation preview 📚: https://metatrain--854.org.readthedocs.build/en/854/

@HannaTuerk
Copy link
Contributor

Thanks Philip! Something definitely is still wrong with the rendering, the Tutorials are in 'Tutorials' and in the main tree:
image
Besides this I will check the code changes now

@PicoCentauri PicoCentauri force-pushed the doc-restructure branch 2 times, most recently from 7563469 to 0be65ea Compare October 22, 2025 15:11
@PicoCentauri
Copy link
Contributor Author

Thanks Philip! Something definitely is still wrong with the rendering, the Tutorials are in 'Tutorials' and in the main tree: image Besides this I will check the code changes now

Should be fixed. Thanks!

@frostedoyster
Copy link
Collaborator

cscs-ci run

@frostedoyster frostedoyster enabled auto-merge (squash) October 27, 2025 09:15
@frostedoyster
Copy link
Collaborator

cscs-ci run


# %%
#
# Check outliers with ``Chemiscope``
Copy link
Contributor

Choose a reason for hiding this comment

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

Not sure why I am getting this here (can you vertify if you also see the same? the original example does not have it, but also does not display the chemiscope image):
image

Copy link
Contributor Author

Choose a reason for hiding this comment

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

on the web version it render but it also shows the error.

Copy link
Contributor

Choose a reason for hiding this comment

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

So this is not a big issue, I would say we could also merge this with the error message for now, since it is still rendering.
Maybe @Luthaf knows how to fix this?

Copy link
Member

Choose a reason for hiding this comment

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

Can you share the input JSON? Assertion error are always bugs, users should not see them =)

Copy link
Member

Choose a reason for hiding this comment

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

(we can still merge for sure, I'll see about fixing this on the chemiscope side)

@PicoCentauri PicoCentauri force-pushed the doc-restructure branch 3 times, most recently from cb2d01b to b2693e3 Compare October 27, 2025 11:17
@@ -15,8 +15,7 @@ mtt --help
# We now demonstrate how to ``train`` and ``evaluate`` a model from the command line.
# For this example we use the :ref:`architecture-soap-bpnn` architecture and a subset of
# the `QM9 dataset <https://paperswithcode.com/dataset/qm9>`_. You can obtain the
Copy link
Contributor

Choose a reason for hiding this comment

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

links for me to https://huggingface.co/papers/trending , I would guess we rather want the original qm9 paper? we can also use :doi: to link the paper directly

../examples/basic_usage/usage
custom_dataset_conf
advanced_base_config
override
Copy link
Contributor

Choose a reason for hiding this comment

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

the fine-tuning example here should be deleted from this section. Also from my point of view, it looks like it is outdated and can just be completely deleted, maybe @cesaremalosso can you also comment on whether this file can be completely deleted? I think it has been replaced by an example in the beginners section

Copy link
Contributor

Choose a reason for hiding this comment

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

hmm but also the fine-tuning in the beginner section links to this.
The reason why I thought it is outdated is that the file refers to a 'fine-tuning example' in the advanced concepts, that does not exist anymore. Can someone from the fine-tuning committee clean this up?
Also, a unified spelling of 'fine-tuning' would be good if this is kept

@PicoCentauri PicoCentauri disabled auto-merge October 27, 2025 12:27
@PicoCentauri
Copy link
Contributor Author

cscs-ci run

@PicoCentauri
Copy link
Contributor Author

cscs-ci run

@PicoCentauri
Copy link
Contributor Author

cscs-ci run

@PicoCentauri PicoCentauri merged commit 4ef6a91 into main Oct 27, 2025
16 checks passed
@PicoCentauri PicoCentauri deleted the doc-restructure branch October 27, 2025 14:44
HowWeiBin pushed a commit that referenced this pull request Oct 30, 2025
HowWeiBin pushed a commit that referenced this pull request Oct 30, 2025
HowWeiBin pushed a commit that referenced this pull request Oct 31, 2025
SanggyuChong pushed a commit that referenced this pull request Nov 9, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants