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.
I’m not sure to see where the advantages are. But if you thought about it carefully and came to the conclusion that it’s better with another repo, why not.
Could it be merged or used to enhance “try-gmt” ?
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.
I like the idea of the separate repository for tutorials. Actually, @maxrjones already setup a similar repository at GitHub - GenericMappingTools/gmt-examples: Tutorials and guides for the Generic Mapping Tools a few months ago. We could either start a new repository or work on that one.
- Built with jupyterbook using the
sphinx-gmt extension for running the examples.
Why jupyterbook? Is it better than sphinx?
So the docs will not be moved? This is only for a (new) tutorial?
@maxrjones already setup a similar repository at https://github.com/GenericMappingTools/gmt-examples a few months ago. We could either start a new repository or work on that one.
Ah thanks, I had missed that one. My thought was to have more written tutorial content, which would be a mixture of the existing tutorials in the docs and the course material for the workshops.
I’d probably leave gallery examples and very short and brief things for the docs in the gmt repo. The GMT China website is more what I had in mind for this.
Why jupyterbook? Is it better than sphinx?
It uses sphinx under the hood but the setup is easier and it has some nice perks, like out-of-the-box markdown and Jupyter notebook support, simpler configuration and building, etc.
I was thinking something like these examples:
The plan would be to move the “tutorials” and “cookbook” away but keep the gallery, reference, and other pages like that which are more closely tied to a particular version of GMT.
To clarify this a bit, I see this as being the material we’d use to teach workshops and a reference to point people to after the workshop.
Great ideas @leouieda!
A JupyterBook setup for the upcoming UNAVCO short course seems great to me, since it would be more easily updated for subsequent years than the current 1 repository per year setup.
Super glad to hear that you’re interested in getting it set up!
1 Like
Thanks, Max! I’m not sure I’ll have this done by this years course but I figure it’s something worth investing in since the plan is to keep doing the workshops and expand them in the future.
I’ve started prototyping a Jupyter Book for the EGU22 short course at Initialize Jupyter Book by weiji14 · Pull Request #3 · GenericMappingTools/egu22pygmt · GitHub. Preview at https://www.generic-mapping-tools.org/egu22pygmt.
First impressions is that the setup wasn’t too bad, they’ve got pretty good step by step documentation at Create your first book. Also the instructions to publish to GitHub Pages via GitHub Actions was a bonus! Technically, it’s just sphinx under the hood, but with a nicer set of defaults and a more modern theme.
I think we can play around with this for EGU22 and as a testbed, and if we like it, we can put some effort into GitHub - GenericMappingTools/gmt-examples: Tutorials and guides for the Generic Mapping Tools.
1 Like
I think that using jupyterbook for EGU22 worked really well and that it would be a good option for other short courses.
@leouieda I have a bit of free time this weekend, so I’ll create a new gmt-for-geodesy repository to try out a jupyterbook setup. We can move the content to a more generic tutorials setup afterwards if needed, but it would be good to have a repository that can host issues for coordinating this year’s short course.
2 Likes
