Gallery plots for each projection

[leouieda]

Description of the desired feature

The user documentation contains a gallery of projections available. The plots showcase the projection so it's easy to choose which one you want (by clicking an image instead of having to google the name). We need to fill out this gallery with all projections listed in https://www.generic-mapping-tools.org/gmt/latest/proj_codes_GMT.html

To make a gallery plot, place a script that generates the figure in examples/projections and sphinx-gallery will take care of the rest. The file must have a specific format (see the other examples). Ideally, each projection should show a case in which it's ideal (e.g. not using Mercator for high latitudes).

Any help with this is greatly appreciated! We can build this out slowly, one example at a time.

[DefUs3r]

Sir,
I would like to take up this issue. I am a beginner and I have no idea of the codebase and a very slight idea of what this library does. I would like to make my first commit here. Can you help me out?

[seisman]

There is a chapter "GMT Map Projections" in the GMT cookbook. We can copy the examples.

[leouieda]

Thanks, @seisman. I was wondering where that was. I want to try this out here and hopefully copy some of it over to the GMT docs later on.

[leouieda]

👋 Hi @DefUs3r, thanks for offering to help! Please have a look at our Contributing Guide. You will need at least a bit of mapping knowledge, though, since the goal is to write example scripts.

[phloose]

I have a background in geoinformatics and i am slightly familiar with projections so i would like to give this a try. The commands used would be ideally the ones from the GMT Map Projections page @seisman mentioned? I also found the grouping of the projection parameters on this page into cylindrical, conic, azimutal, miscellaneus and non-geographic projections very good to make it easier for the user to select what he needs. Maybe a short description, what the primary purpose of a certain projection is, would be helpful too, especially for new, unexperienced users.

I am already playing around with the examples and if i find it suitable will file a pull request if you don't mind?!

[leouieda]

Hi @xibalba01 we don't mind PRs at all 🙂 I agree that having a small description of when the projection should be used would be very helpful! I like the idea of grouping the examples as well.

[phloose]

I have problems building the docs under windows:

Running make all or make html yields in:

(pygmt) C:\Users\mo3kLo4r\Documents\Code\OpenSource\pygmt\doc>make all
ECHO ist ausgeschaltet (OFF).
"Building API docs."
ECHO ist ausgeschaltet (OFF).
sphinx-autogen -i -t _templates -o api/generated api/*.rst
[autosummary] generating autosummary for: api/*.rst
[autosummary] writing to api/generated
Traceback (most recent call last):
  File "C:\Users\mo3kLo4r\Miniconda3\envs\pygmt\Scripts\sphinx-autogen-script.py", line 10, in <module>
    sys.exit(main())
  File "C:\Users\mo3kLo4r\Miniconda3\envs\pygmt\lib\site-packages\sphinx\ext\autosummary\generate.py", line 421, in main
    app=app)
  File "C:\Users\mo3kLo4r\Miniconda3\envs\pygmt\lib\site-packages\sphinx\ext\autosummary\generate.py", line 137, in generate_autosummary_docs
    items = find_autosummary_in_files(sources)
  File "C:\Users\mo3kLo4r\Miniconda3\envs\pygmt\lib\site-packages\sphinx\ext\autosummary\generate.py", line 253, in find_autosummary_in_files
    errors='ignore') as f:
  File "C:\Users\mo3kLo4r\Miniconda3\envs\pygmt\lib\codecs.py", line 898, in open
    file = builtins.open(filename, mode, buffering)
OSError: [Errno 22] Invalid argument: 'api/*.rst'
make: *** [api] Fehler 1

A short workaround was to not use api/*.rst and instead use index.rst explicitly from the api/ folder, but then i get another error when trying to build the html pages:

(pygmt) C:\Users\mo3kLo4r\Documents\Code\OpenSource\pygmt\doc>make html
ECHO ist ausgeschaltet (OFF).
"Building API docs."
ECHO ist ausgeschaltet (OFF).
sphinx-autogen -i -t _templates -o api/generated api/index.rst
[autosummary] generating autosummary for: api/index.rst
[autosummary] writing to api/generated
ECHO ist ausgeschaltet (OFF).
"Building HTML files."
ECHO ist ausgeschaltet (OFF).
sphinx-build -b html -d _build/doctrees   . _build/html
Running Sphinx v1.8.5
loading intersphinx inventory from https://docs.python.org/3/objects.inv...
loading intersphinx inventory from https://docs.scipy.org/doc/numpy/objects.inv...
loading intersphinx inventory from http://pandas.pydata.org/pandas-docs/stable/objects.inv...
intersphinx inventory has moved: http://pandas.pydata.org/pandas-docs/stable/objects.inv -> https://pandas.pydata.org/pandas-docs/stable/objects.inv
loading intersphinx inventory from http://xarray.pydata.org/en/stable/objects.inv...
generating gallery...
Der Befehl "gswin64c" ist entweder falsch geschrieben oder
konnte nicht gefunden werden.
WARNING: C:\Users\mo3kLo4r\Documents\Code\OpenSource\pygmt\examples\gallery\coast\borders.py failed to execute correctly: Traceback (most recent call last):
  File "C:\Users\mo3kLo4r\Miniconda3\envs\pygmt\lib\site-packages\sphinx_gallery\gen_rst.py", line 480, in _memory_usage
    out = func()
  File "C:\Users\mo3kLo4r\Miniconda3\envs\pygmt\lib\site-packages\sphinx_gallery\gen_rst.py", line 465, in __call__
    exec(self.code, self.globals)
  File "C:\Users\mo3kLo4r\Documents\Code\OpenSource\pygmt\examples\gallery\coast\borders.py", line 25, in <module>
    fig.show()
  File "c:\users\mo3klo4r\documents\code\opensource\pygmt\pygmt\figure.py", line 272, in show
    fmt="png", dpi=dpi, anti_alias=True, as_bytes=True, transparent=True
  File "c:\users\mo3klo4r\documents\code\opensource\pygmt\pygmt\figure.py", line 342, in _preview
    self.savefig(fname, dpi=dpi, **kwargs)
  File "c:\users\mo3klo4r\documents\code\opensource\pygmt\pygmt\figure.py", line 225, in savefig
    self.psconvert(prefix=prefix, fmt=fmt, crop=crop, **kwargs)
  File "c:\users\mo3klo4r\documents\code\opensource\pygmt\pygmt\helpers\decorators.py", line 187, in new_module
    return module_func(*args, **kwargs)
  File "c:\users\mo3klo4r\documents\code\opensource\pygmt\pygmt\helpers\decorators.py", line 282, in new_module
    return module_func(*args, **kwargs)
  File "c:\users\mo3klo4r\documents\code\opensource\pygmt\pygmt\figure.py", line 165, in psconvert
    lib.call_module("psconvert", build_arg_string(kwargs))
  File "c:\users\mo3klo4r\documents\code\opensource\pygmt\pygmt\clib\session.py", line 490, in call_module
    module, status, self._error_message
pygmt.exceptions.GMTCLibError: Module 'psconvert' failed with status code 78:
psconvert [ERROR]: Error opening HKLM key
psconvert [ERROR]: Failed to parse response to GhostScript version query [n = -1 0 0].

psconvert [ERROR]: Error opening HKLM key
Der Befehl "gswin64c" ist entweder falsch geschrieben oder
konnte nicht gefunden werden.
psconvert [ERROR]: Failed to parse response to GhostScript version query [n = -1 0 0].

Exception occurred:
  File "c:\users\mo3klo4r\documents\code\opensource\pygmt\pygmt\clib\session.py", line 490, in call_module
    module, status, self._error_message
pygmt.exceptions.GMTCLibError: Module 'psconvert' failed with status code 78:
psconvert [ERROR]: Error opening HKLM key
psconvert [ERROR]: Failed to parse response to GhostScript version query [n = -1 0 0].
The full traceback has been saved in C:\Users\mo3kLo4r\AppData\Local\Temp\sphinx-err-_hpy72rb.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!
make: *** [html] Fehler 2

Somehow psconvert can't find ghostscript even though its installed... Strange, since normal plotting within a jupyter notebook works. In the beginning i didnt had ghostscript installed so no plot worked and i got the same error. Any ideas?

Under linux building the docs works, although initially i had problems with ghostscript. psconvert produced postscript files with decimal values that used a comma instead of a period. I could fix it by setting LC_NUMERIC to en_US.UTF-8 (i have a german system...)

EDIT

Ok obviously if ghostscript on windows is NOT installed via conda pygmt/gmt doesnt find its executable...

[phloose]

I split the projections folder into the main groups by creating subfolders with their own README.txt like it is described in the sphinx-gallery-docs. Now it appears like i was thinking it makes the most sense.

Do you think it would make sense to write a small general introduction for every type of projection?