Add a new documentation group for "technical explanations" or "showcases"

[seisman]

Justification codes like BL and TR are commonly used in GMT and PyGMT. Currently, we have explanations like:

The justification is a two-character code that is a combination of a horizontal (L\ (eft), C\ (enter), or R\ (ight)) and a vertical (T\ (op), M\ (iddle), or B\ (ottom)) code.

Instead of repeatedly explaining justification codes in different plotting methods, I feel it makes more sense to have a separate page explaining justification codes then we can link to this page when necessary.

Looking at the divio documentation system, I feel it should belong to "Reference" documentation, rather than "Tutorials". Currently, we have an "API Reference" page (https://www.pygmt.org/dev/api/index.html), but apparently "justification" is not an API thing. Maybe we need another section like "Technical Reference" or something else?

[yvonnefroehlich]

Thanks @seisman for pointing out this aspect! This documentation concept page looks interesting - thanks for posting the link!

We have multiple docstrings and examples that mention these 2-character codes for the position and justify parameters:

• https://www.pygmt.org/dev/gallery/embellishments/colorbar.html
• https://www.pygmt.org/dev/tutorials/basics/text.html#justify-parameter
• https://www.pygmt.org/dev/api/generated/pygmt.Figure.text.html
• etc.

I agree it would be better to have this bundled in one place, and link to it in the docstrings and examples.

If we decide on any kind of "technical reference", what would make sense to include beside these 2-character codes? Maybe:

• GMT colors (including a link to this new Color-Picker)
• GMT custom symbols (see issue Gallery/tutorial example showing how to use/create custom symbols #1349)
• GMT bit and hachure patterns (see gallery example at https://www.pygmt.org/dev/gallery/symbols/patterns.html)

[seisman]

If we decide on any kind of "technical reference", what would make sense to include beside these 2-character codes? Maybe:

• GMT colors (including a link to this new Color-Picker)
• GMT custom symbols (see issue Gallery/tutorial example showing how to use/create custom symbols #1349)
• GMT bit and hachure patterns (see gallery example at https://www.pygmt.org/dev/gallery/symbols/patterns.html)

I believe there are a lot that can be added to this "section":

1. List of plotting symbols/markers, similar to https://matplotlib.org/stable/api/markers_api.html
2. List of supported fonts?
3. How PyGMT parameters converts to GMT command line options [very technical but maybe useful to some new maintainers and even users]
4. Explanation of some common options/parameters.
5. How the "current" CPT works.
6. ...

[seisman]

Ping @GenericMappingTools/pygmt-maintainers for more discussions on this.