Hey all,
I’ve been thinking about the state of the GMT docs for a while and recently had a chat with Paul about this. I’d like to propose the following:
Create a separate website for GMT tutorials (tutorials.generic-mapping-tools.org) that refers only to the latest release. This would be sourced from a github.com/GenericMappingTools/tutorials repo.
Why do this:
- The current setup in the
gmt
repo is a bit overly complicated with cmake being involved and a bit unconventional sphinx setup. - Making changes there is not trivial and that repository is very active and intimidating.
- The GMT basics don’t change so often that it would be a problem having a single version.
- This repo can be very minimal in setup to make it as easy as possible for people to contribute learning material
Features of this website/repo:
- Built with jupyterbook using the
sphinx-gmt
extension for running the examples. - Include tutorials in different tiers: beginner, intermediate, advanced. The beginner tutorial would be a written out version of the UNAVCO material. Some modules could be discipline specific.
- "HowTo"s for particular tasks (making this fancy map, downsampling a grid, etc). These would be prime for recruiting expert users.
Advantages:
- Hopefully easier to recruit new contributors by reducing overhead
- Collect some of the material being developed by third-parties out there (so many people have GMT course notes)
- Serve as the basis for the UNAVCO workshops and other future workshops (like the Software Carpentry material)
- Can slowly be sourced from the current ‘tutorials’ and ‘cookbook’ in the docs but with a more easily searchable format
Disadvantages:
- Another repo to maintain
- Separate from the source so could get out of sync (already happens anyway)
I’d be willing to set this up if people are interested. I’ve used JupyterBook recently and could get it started with not that much effort. Let me know what people think.