Notebooks, examples and data files

[michaelchin]

Currently the gplately notebooks and data files are excluded from the package. The reason is that the notebooks and associated data files are large. And users may have trouble in finding them. For example, in my computer, they are at ~/micromamba/envs/gplately/lib/python3.11/site-packages/gplately/notebooks. I can find them, but I guess other people might find it easier to just download them from Internet.

PTT uses install_documentation() to copy examples from ~/micromamba/envs/gplately/lib/python3.11/site-packages/ptt/Examples to a user specified folder. Should we write a function to grab notebooks and data files from Internet, instead of installing them in users' computers by default?

Discussion is needed and decision need to be made.

[jcannon-gplates]

Could you remind me what was the reason to put PTT inside GPlately?

I think it was to have less packages to maintain, especially since PTT development had slowed down. And also so users could get it all in one place/package. We will still have pip and conda PTT in the wild, but users should transition to GPlately.

they are at ~/micromamba/envs/gplately/lib/python3.11/site-packages/gplately/notebooks. I can find them, but I guess other people might find it easier to just download them from Internet.

As you noted, this was the reason for adding install_documentation to PTT (because hard for users to find it in site-packages). We also do this in pyBacktrack (copy the examples and supplementary scripts to a directory specified by the user with, eg, python -c "import pybacktrack; pybacktrack.install_examples('~/my_pybacktrack_examples')") - but the data is not too large there, so stuffing it inside the package is fine.

Should we write a function to grab notebooks and data files from Internet, instead of installing them in users' computers by default?

Sounds fine to me, especially if the example data is quite large. I know getting PyPI to approve package size updates requires a bit of waiting (had that with pyBacktrack when adding new topological models to the package).

Alternatively could just document the download link (for the examples) in the documentation, and the user manually downloads.

[michaelchin]

Alternatively could just document the download link (for the examples) in the documentation, and the user manually downloads.

I think John's suggestion is good. @GPlates/gplately-dev

[jcannon-gplates]

I just realised that there will be different versions of the examples. But you now have different versions of the documentation, so each doc version could point to the associated example version download. Or just keep two versions of the examples/data: (1) latest public release, (2) latest dev (master).

[michaelchin]

Shall we delete https://github.com/GPlates/gplately/blob/master/gplately/ptt/documentation.py?

[michaelchin]

the notebooks/examples can also be put into a dock image