GenericMappingTools / GenericMappingTools/gmt

DOC: Combine the modern and classic ReST files into a single file

Open
#8,486 3 comments 0 reactions 0 assignees View on GitHub
discussion
Dominant language
C
Stars
979
Forks
414
Avg merge
17h 26m
Merged PRs (30d)
54

Description

For almost all plotting modules, we usually have two separate ReST files for modern and classic modes, respectively. For example, we have `image.rst` and `psimage.rst` and `gmtlogo.rst` and `gmtlogo-classic.rst`.

More ReST files usually mean more maintenance burden, especially sometimes we may fix or update the modern mode examples in one file, but forget to update the corresponding examples in another file.

So, I guess it makes more sense to have only one documentation file for a single module. Usually, the differences of modern and classic ReST files are:

- `-K`/`-O`/`-P` is only available in classic mode
- Examples have different syntax.

For point 1, this can be addressed by emphasizing the these options are classic-mode only. For point 2, modern/classic modes can be switched using sphinx-design's tab directive (https://sphinx-design.readthedocs.io/en/furo-theme/tabs.html).

#8487 is an example PR showing how it works.

The title:

![Screenshot from 2024-05-13 12-01-39](https://github.com/GenericMappingTools/gmt/assets/3974108/9dfa6fc4-52f4-4864-bab7-46b6420c1c2c)

Classic-only options:

![Screenshot from 2024-05-13 12-02-19](https://github.com/GenericMappingTools/gmt/assets/3974108/a700dfe9-4b32-4861-8d7c-14e111358249)

Modern-mode example:

![Screenshot from 2024-05-13 12-02-55](https://github.com/GenericMappingTools/gmt/assets/3974108/051d6ce2-c5c8-4acc-92c7-9d6200959e8e)

Classic-mode examples (after clicking the "Classic mode" Tab:
![Screenshot from 2024-05-13 12-03-10](https://github.com/GenericMappingTools/gmt/assets/3974108/5b74683a-d0af-44e4-b663-aa7f4d73b63b)

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.