Recommendations related to the GMT.jl documentations

[Leon6j]

I'm not really reporting an issue with the GMT.jl. Just want to share some of my thoughts in terms of how to improve the GMT.jl documentation.

1. It would be great if each of the function documentation starts with a real syntax with as many input arguments as you can provide with that function, instead of just using something like this: f(cmd0::String="", arg1=nothing, kwargs...).

2. The same thing is true for each of the input arguments. Instead of using something like, between:: [Type => Array | Str]. Please consider offering the real input argument syntax here, e.g., between=“[low]/[high]/[between]” or -Si[low]/[high]/[between], and then followed by explaining each of the elements

3. Please offer one or two examples for each function, with explanations for how each argument is controlling which part of the function. Ideally, these examples should work independently and be able to lead to a map plot. That way, users can test the code themselves.

4. It will also be helpful to list any related functions. For example, if the function of interest is "grdclip", it will be nice to list related programs like "clip", etc. here.

Many thanks for your hard work to create these wonderful tools and for putting together the current draft of the GMT.jl documentation. I hope you would not mind considering these recommendations when you release the next version of the documentation. This can be a summer intern's project, for example.

[joa-quim]

Thanks. I'm closing this PR, however, because most of the suggestions are already the practice. What really needs to be done is to extend that practice to many more modules that have only the mentioned scarcity of information. But that is a very large task, which advances ... but slowly.

[adigitoleo]

I'm a bit busy currently but the documentation is likely the first thing I will try to help improve, because that will help me understand the internals better.

However, I'm not sure that typing out the entire call signatures can be done without causing a lot of clutter. Many GMT.jl functions accept a large number of arguments. I think the list-based approach currently in place makes sense, but it could be a bit cleaner and I agree that the cross-referencing could be improved.

[joa-quim]

Cross references between modules are very easy to do and making PR should be easy too ... as long as we have models to link to 😄
See the end of the recently added blocks* man pages.