EAMxx: add 2025 tutorial presentations

[mahf708]

adds the presentation from the 2025 EAMxx tutorial at the E3SM All-Hands. This PR does that by revisiting installing the python dependencies in the gh-pages workflow (moving from pypi to conda) and utilizing a nodejs framework (marp) to create slide decks out of markdown files.

[BFB]

[github-actions]

PR Preview Action v1.6.0
🚀 View preview at https://E3SM-Project.github.io/E3SM/pr-preview/pr-7101/
Built to branch gh-pages at 2025-03-09 14:59 UTC. Preview will be ready when the GitHub Pages deployment is complete.

[mahf708]

To reviewers, the source code of these presentations is a pretty plain markdown you will find in the PR files page. The resulting presentations can be viewed here: https://docs.e3sm.org/E3SM/pr-preview/pr-7101/EAMxx/user/presentations/. Take a look and let me know.

For @rljacob, this introduces a slightly different workflow setup that others may wish to make use of for their presentations. I also converted the pypi-based python dependency installation to conda because pypi no longer suffices.

For @xylar, jfyi and in case you have some advice on the micromamba setup (if you prefer we follow different procedures to keep a consistent approach across the project, happy to edit here, just let me know)

[rljacob]

Please explain the workflow you are envisioning.

[mahf708]

Please explain the workflow you are envisioning.

I should clarify, everything we have working for docs so far will remain working with no changes whatsoever. In this PR, I show this our docs workflow can be generalized to presentations if people wish to store their presentations in github repos (here for project presentations like those EAMxx tutorial ones or in private repos for their own work). The big advantage is that tracking markdown in git is much friendlier than other formats.

Here's how I envision one could add more presentations:

• write plain markdown with minor annotations like in this PR (e.g., see components/eamxx/docs/_presentations_srcs/eamxx-tutorial-2025-part1.md, the main thing to note is the customization atop the file and how --- are "slide" breakers)
• convert the markdown files to html in the source tree, e.g., via marp as I did in the workflow yml file, before calling mkdocs to convert the docs, but make sure the converted files don't persist (so added to .gitignore)
• mkdocs will take them into account when building the html webiste (e.g., see components/eamxx/docs/user/presentations.md for how to link them)

[rljacob]

But doesn't this mean you have to write your presentation in markdown to start? I don't understand the point of even making this workflow available. You had a perfectly good pdf of the tutorial on our world readable confluence site. Just link to that.

[mahf708]

In the ethos of "docs near and tracked with the code" ... a PDF isn't easily git-trackable. That's the main advantage. We can easily update these markdown files for the next presentations. Also, having the presentation be in html is helpful. Can natively copy out of it (as opposed to copying out of PDF which may or may not work)

[rljacob]

If you see the tutorial as something you want to generalize and expand as an integral part of the user's guide, this makes sense. But we don't want every presentation ever to be made about eamxx to live in eamxx/docs.

[mahf708]

If you see the tutorial as something you want to generalize and expand as an integral part of the user's guide, this makes sense. But we don't want every presentation ever to be made about eamxx to live in eamxx/docs.

Oh, I see the potential misunderstanding here. This is just for a very LIMITED set of presentations we want to make available as part of the "living" docs, like the tutorial. But we definitely won't be adding other presentations. And, I expect the tutorial presentations to be updated, rather than adding more. Sorry, I should've been clearer about the intentions...

[mjschmidt271]

Nice work on this. The slides look excellent, and I like the motivation behind using markdown for better version tracking