Consolidating the source text for common options documentation

[maxrjones]

Description of the desired feature

Originally discussed at https://github.com/GenericMappingTools/gmt/pull/4918

The GMT common options are documented in the gmt manpage and the cookbook standardized command line options chapter. The source files for the common options documentation should be consolidated due to the amount of redundant information in these files, which can lead to errors when adding new features or enhancements.

Here is the current structure of these two documentation sources:

• GMT manpage - primary source is doc/rst/source/gmt.rst, which has include directives for separate ReST files for each standard option (named doc/rst/source/explain_-*.rst_).
• GMT cookbook - all documentation is located in doc/rst/source/cookbook/options.rst

Here are two options for consolidating the documentation:

Option 1 Move the syntax and description (without examples) sections from doc/rst/source/cookbook/options.rst to the explain_-*.rst_ files and then include those files both in the cookbook and the gmt manpage.

Benefits of this method

• No need for PyGMT to change their documentation (which currently links to sections in https://docs.generic-mapping-tools.org/dev/gmt.html)
• Users that are bandwidth limited can view https://docs.generic-mapping-tools.org/dev/gmt.html for predominantly text-based information (missing examples; comparatively limited documentation for -J).

Option 2 Only include a simple table with the common options syntax in https://docs.generic-mapping-tools.org/dev/gmt.html that links to full options in cookbook

Benefits of this method

• Simpler documentation structure (could encourage new collaborators)
• 39 fewer files in doc/rst/source

For some context about the data usage discussion, here's the amount transferred when loading the various pages:

• https://docs.generic-mapping-tools.org/dev/gmt.html#the-common-gmt-options (750 KB)
• https://docs.generic-mapping-tools.org/dev/cookbook/options.html (1.7 MB)
• https://docs.generic-mapping-tools.org/dev/std-opts.html (640 KB)

Are you willing to help implement and maintain this feature? Yes

[maxrjones]

Pinging @joa-quim, @PaulWessel, and @seisman for opinions. The fact that PyGMT (and possible other resources) links to the individual common option sections in https://docs.generic-mapping-tools.org/dev/gmt.html#the-common-gmt-options makes me hesitant to remove them.

edit: it would be easy to update the PyGMT links, the bigger issue is whether others may be relying on those particular sections existing as well.

[joa-quim]

Removing that page would made invalid all links printed by all Julia modules online help. I already gave opinion that links to common option should be kept in the lighter gmt.html page and that this has nothing to do with having singles files with the options docs, which can then be include in both the cookbook or and the gmt.rst.

Sorry, not all links. Only those of the common options.

[maxrjones]

Finally done 🎉