Automatically push copies of Cantera examples to dedicated repository

[ischoegl]

Changes proposed in this pull request

A dedicated repository containing examples would make it easy to point new users to an easily accessible location where all examples are collected.

• Automatically push cantera examples to dedicated repository whenever a PR is merged into main (this uses the GH Action push-directory-to-another-repository)
• Collect both samples and interfaces/cython/cantera/examples
• Add a customized README.md

Note: This PR is meant to facilitate discussion. The destination repository currently does not exist (although the CI run was tested on ischoegl/cantera/actions/runs/1716150523). It is possible to tweak this idea further to copy to sub-folders in the destination repository. This means that it would be easy to copy files from Cantera/cantera-jupyter as well.

If applicable, fill in the issue number this pull request is fixing

N/A, but see Cantera/enhancements#51, Cantera/enhancements#129

If applicable, provide an example illustrating new features this pull request is introducing

While there is no destination repository in the main Cantera repository at the moment, a (no-frills) example can be checked at ischoegl/cantera-samples

Checklist

• The pull request includes a clear description of this code change
• Commit messages have short titles and reference relevant issues
• Build passes (scons build & scons test) and unit tests address code coverage
• Style & formatting of contributed code follows contributing guidelines
• The pull request is ready for review

[speth]

So is the idea that the cantera-jupyter repository would also separately push to this repository?

I guess what I'd like to understand is how you see this repository being used. For accessing individual examples, I think the index at https://cantera.org/examples is always going to offer us the most flexibility in terms of presenting the examples to users, and we already have a number of partially-executed or at least planned enhancements to that interface. The other scenario I can imagine is wanting to quickly download all of the examples, which was why I suggested packaging a .zip file.

This interface provides that in a roundabout way, since Git does offer that as an option under the "Code" button. But I am a little concerned that this will encourage users to clone this repo and make changes in it, which isn't really ideal since it would be difficult to bring any such changes back in to the original repos.

[decaluwe]

@speth I can see the logic in that, if I wanted to actually run an example locally, there are two inconveniences:

• The average user might not want to download the source code at all, and
• Even for those that do, navigating to the particular folder where there example is buried is a bit of a hassle.

which was why I suggested packaging a .zip file.

Can you say more, here? Do you mean packaging a zip file that could be downloaded from the website? If so, i agree that this might be a better solution, in that for case 1 above, having to get up to speed on git might already be too large a barrier, and also to avoid your concern, about people committing changes to a repo that isn't passed back to the source code.

That said, I suppose that the two approaches are not mutually exclusive.

[decaluwe]

Ah, just found the discussion on Cantera/enhancements#129 Catching up...

[bryanwweber]

I guess what I'd like to understand is how you see this repository being used.

@speth One possible use would be to build the website. It would be easier to clone a sample-specific repo and pull examples from there rather than the (much larger) Cantera/cantera repo.

But I am a little concerned that this will encourage users to clone this repo and make changes in it, which isn't really ideal since it would be difficult to bring any such changes back in to the original repos.

I think we can add a README that says in big bold letters DO NOT CLONE THIS SUBMIT CHANGES OVER HERE, an issue template that says the same thing, and close any PRs that are opened, either automatically or by hand.

• Even for those that do, navigating to the particular folder where there example is buried is a bit of a hassle.

@decaluwe This is being discussed as well in Cantera/enhancements#51

@ischoegl If this goes forward (I don't have a strong opinion either way), this would be a good place for @CanteraBot to make the commits.

[ischoegl]

@speth and @decaluwe

The other scenario I can imagine is wanting to quickly download all of the examples, which was why I suggested packaging a .zip file.

One nice thing here would be that we can 'release' examples as a zip file on a cantera-samples repo every time there is a cantera release. That way, users can download examples as available for each stable version, instead of having to dig through git or look at individual examples in old docs. Obviously, there's the possibility to backport for 2.4 and 2.5.1.

[ischoegl]

Regarding some of the other comments:

But I am a little concerned that this will encourage users to clone this repo and make changes in it, which isn't really ideal since it would be difficult to bring any such changes back in to the original repos.

I think that can be handled by suitable PR templates.

this would be a good place for @CanteraBot to make the commits.

Not sufficiently familiar, but sure!

One possible use would be to build the website. It would be easier to clone a sample-specific repo and pull examples from there rather than the (much larger) Cantera/cantera repo.

Had not thought of that. But that offers another interesting option: a CI job (triggered on Cantera/cantera) could execute jupyter notebooks and upload the executed ones to cantera-samples. That way, jupyter would be integrated into CI and example notebooks would always be up to date ...

I guess what I'd like to understand is how you see this repository being used.

@speth My overarching objective would be that a stand-alone repo would make it possible to direct new users to a single, easy-to-understand repository, where they can download all examples. As you pointed out in Cantera/enhancements#129, it is somewhat difficult to direct users to ~/.conda/envs/whatever/lib/python3.10/site-packages/cantera/examples/.... I know examples can be viewed on / downloaded from the website, but this would be a one-stop-shop.

[ischoegl]

Not pursuing this beyond this point.