Add a sphinx docs structure for hosting gmt examples

[maxrjones]

This PR sets up a sphinx project for hosting the GMT simple examples and tutorials.

Relates to GenericMappingTools/gmt#5364.

[maxrjones]

@seisman, is 'Import Git Repository' in Vercel the proper way to setup the vercel previews for this?

[seisman]

@seisman, is 'Import Git Repository' in Vercel the proper way to setup the vercel previews for this?

I think yes.

[leouieda]

👏🏽 awesome work on this @meghanrjones! Makes a lot of sense to have a separate set of user contributed examples. And it's a good way to get them used to the setup and being able to contribute to the docs afterwards.

Just FYI I looked into what it would take to get sphinx-gallery to work with a bunch of bash scripts instead of Python scripts a while ago. Capturing the images is easy enough but getting it run the code and create the rst files is trickier. There was a discussion of this in sphinx-gallery/sphinx-gallery#421 (using the Jupyter machinery to execute code in basically any language) but doesn't seem to have been implemented yet.

[leouieda]

Since there is nothing here besides the sphinx website sources, it may be worth putting everything in the top-level directory instead of docs, like we do on https://github.com/GenericMappingTools/website/. Entirely optional, though.

[leouieda]

Or just plain URL which GMT can read.

This can be tricky depending on the URL. If the data moves, these docs will break and it will be out of our control.

Alternatively, getting their data and uploading somewhere we control (server, Zenodo, whatever) runs into the problem of open licenses (and mostly the lack thereof).

[joa-quim]

I recommend miniforge here instead of Anaconda because it really only comes with the bare minimum and is (somewhat) independent from Anaconda Inc.

Hi Leonardo,
I am sorry but I never saw that and I reinstalled my miniconda (that was using 18 GB) not long ago. It may be true on first install (if user refuses to install what is proposed, don't remember) but it quickly jumps to the multi Gigs. Mine has already recovered to 8 GB.

[joa-quim]

Another thing. It would be nice to anticipate that the examples can be shown both in pure GMT as well as GMT.jl, PyGMT and eventually GMTMEX. If we don't have many it won't be much work to translate between the syntaxes and PyGMT already has quite a few examples that can be used here.

[maxrjones]

One way to support both pure GMT and the wrappers would be to have a toggle button dropdown that contains the equivalent source code in GMT.jl, PyGMT, GMT/MEX. This would be easy to implement. It would be more difficult to host entire separate tutorials/gallery examples for wrappers, mostly because GMT and the wrappers would all need to be installed for the continuous documentation which can be fragile/slow based on try-gmt.

[PaulWessel]

Would we need to support the running of all those wrapper scripts in the CI or do we just support the bash script and simply display the comparable wrapper scripts as is?

[joa-quim]

I was thinking in just providing the the equivalent scripts. Not the burden of setting up an infrastructure to make them pass CI tests. At least not at the beginning. A dropdown menu like the one for selecting different versions of the manual would be good.

[maxrjones]

That sounds good, I can add instructions in a separate PR.

[maxrjones]

I've addressed all the issues raised in the PR comments except these four:

Allow users to contribute scripts without needing a working sphinx installation

I'll work on instructions for how to contribute an example without a local development environment in a separate PR.

Optionally put everything in a top-level directory

I prefer to keep the top-level directory relatively small.

Establish guidelines for datasets used in gmt examples

I'll submit a separate PR with a new contributing guide section for further discussion.

Add toggle buttons to support GMT.jl, PyGMT, and GMTMEX equivalent scripts

I'll create an issue to track this, which can be added in a separate PR.

In the meantime, I'll merge this PR so we have a starting point and will transfer any issues from the GMT repository that can be more appropriately addressed through the GMT examples pages.