Add a new documentation group "Technical References"

[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? [Document the supported 35 standard Postscript fonts in the Technical Reference section #3378]
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.

[yvonnefroehlich]

I apologize for the delayed reply here. Currently I am quite busy with a research project and have only little time to contribute to other things 🙁.

I feel this has partly similarities to the "Technical References" of the GMT documentation. So I think we can focus on PyGMT specific aspects in more detail, and mention topics that are identical to GMT in a more general way and add the link to the "Technical References" for details.

[seisman]

I think we will go with "Technical References" if no further objections.

[seisman]

We have added some documentation to the new "Technical References" section in PR #3378. More documentation will be added to this section in the future, as proposed in the above posts. I think it would be better to open separate issues to track each documentation request.

Closing the issue.