-
Notifications
You must be signed in to change notification settings - Fork 348
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add a page for simple examples #5364
Conversation
Ping @PaulWessel @joa-quim @meghanrjones @Esteban82 @KristofKoch for comments |
This is great, @seisman! I have a few comments and suggestions: I agree this should focus on very simple things to demonstrate them. Might there be separate categories or groups we want to keep separate? I am thinking
Maybe others? I think just having a hodge-podge of examples will be frustrating. |
Yes, similar categories are being used in the PyGMT Gallery and we can also do that in the GMT side. The Edit: More categories are added in commit 8848c52. |
This is an excellent idea!
|
We have talked about this many times. I think we should aim to mimic the example types like the Matplotlib example pages. Don't think the main goal here is to have very simple plots, but to have simple scripts (as much as they can be) to produce practical figs. xy, bars, histograms, images, etc... |
Yes, I agree.
As mentioned by @joa-quim, the scripts should be as simple as possible. Some simple but practical examples can be found at the PyGMT Gallery, the GMT.jl Gallery and Matplotlib Gallery. We can even create some examples from the PyGMT or GMT.jl gallery, so that users can know how to plot the same plot using GMT CLI, PyGMT or GMT.jl.
Yes, any command-line tools should be allowed, but a note should be added to make it clear that external commands are needed.
I would prefer the modern mode only. Mixing modern and classic modes in the examples would make users more confusing. |
Remember that all GMT.jl scripts when using the Vd=1 option will print the generated GMT command that can be run directly (plus the input data file name). |
I like it @seisman – but where to draw the line? Currently the docs for each program have that example section at the end with mostly one-liner examples but without the resulting plots. This might be a good starting point? I feel it is a bit difficult to separate the examples properly. We got some examples in the man pages, some in the cookbook and some on the current examples page. I think we can all agree that the learning curve for the finer points is still rather steep. So to quote @anbj:
would be the best approach in my eyes. Maybe even multiple examples for different options. |
The matplotlib gallery includes a |
Between GMT.jl and PyGMT we already have quite a few of those basic but useful examples. We could gather those that are common, or can be easily implemented in the other wrapper, in a common group. Then each image would have 3 links pointing to the languages in which they can be written. |
One more question: Should the examples be fully self contained? That is, should the code always produce a (finalized) figure? I can think of a couple of cases where a proof-of-concept is enough/the point per se. E.g.
|
And yet more: How does this new section relate to the existing https://docs.generic-mapping-tools.org/latest/users-contrib-scripts.html? |
Great idea. It would be possible to add labels (like here or the keyword in a paper) for each example? I think that it would help the users. Also some scripts from the test folder could be add. |
This section seems the same to me as the showcase on the forum. Could we consolidate? |
Sorry for forgetting this PR for months.
The
I think the examples should be fully self contained so that users can copy the script, run it and then modify it. Without a final figure, people may have to read a long paragraph to understand what the example does and what the magic is.
I think the section is here for some historic reasons, but since there is only one script, we may move it to here.
It's definitely possible to add labels or keywords. It would be better if we can filter examples by lables/keywords, but it's challenging for me (need more knowledge about javascript and other web knowledge),
Yes, but we may have to duplicate the scripts because the doc directory may not be able to access the test directory.
We can also show the examples posted in the forum and add links to them. |
Maybe this could be talk is next community meeting? |
Sounds good, I will add this to the agenda. |
.. image:: https://user-images.githubusercontent.com/3974108/122659135-7cfe0100-d142-11eb-9a3f-e1ecf5b3d35c.png | ||
:width: 80% |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I do not think we should use this strategy for including images hosted on GitHub because anyone who builds the documentation and/or uses the bundle docs offline will not be able to see the images.
Given that there will likely be many small, practical examples (in addition to new tutorial pages depending on funding) and that we want to leverage community contributions for these pages, I think we should consider hosting the examples in a separate repository. Here are my primary reasons:
|
What's the status of this PR ? Do we have a list of examples that need to be done ? |
Sorry again for forgetting this PR. I agree with @meghanrjones's 3 points that a separate repository is a better option for GMT examples. So, As I understand it, what we should do is:
My question is: do we still want to use dvc to manage these example images as mentioned in #5724 or do we just upload these static images to GitHub? |
Sorry for leaving this PR without a response for so long. Since we aren't using these examples as tests, I think we can use the sphinx_gmt extension to generate the images when building the docs rather than storing the static images on GitHub or DAGsHub. Do you mind if I create the |
I'll get started on the |
Description of proposed changes
As mentioned in #4448 and #3320, the current 52 examples in the Gallery page are a little too complicated.
Users may find that simple examples are more useful to learn GMT quickly. For example, both the PyGMT Gallery and the GMT.jl Gallery provides many simple examples. Users may also want to contribute simple examples rather than complicated ones (e.g., #4448 and #3320).
In this PR, I create a new gallery page for simple examples. The new page is called "Examples", and the old "Example Gallery" page is renamed to "Gallery" (We can change them to other names after some discussions).
The "Gallery" page contains complicated examples, and the scripts are located in the
doc/examples
directory.The new "Examples" page contains simple examples (e.g., plotting lines with different styles). Each example is stored in the
doc/rst/source/examples/exXXX
directory. Each directory should contain the following files:index.rst
file explaining the exampleexXXX.sh
script fileIn this PR, I add a demo example "ex001" to show how the new page works. The generated image (ex001.ps) is not included, because
Preview: https://gmt-git-example-page-gmt.vercel.app/examples/index.html