GenericMappingTools / GenericMappingTools/gmt

Document option changes in the HTML documentation

Open
#5,615 14 comments 0 reactions 0 assignees View on GitHub
feature request
Dominant language
C
Stars
979
Forks
414
Avg merge
17h 26m
Merged PRs (30d)
54

Description

**Description of the desired feature**

I'll take the recent changes in the `psconvert` module as an example.

In PR #5583, some modifiers of the **-A** option are moved to the **-I** option. The changes are handled in a compatible way, so that old scripts using `-A+m2c` still works.

However, users may need to read and understand old scripts that were written by someone else a few years ago. They definitely would be very confused when they see `-A+m2c` in the old scripts, but don't see such usage in the GMT HTML documentation.

I think we should use [Sphinx directives `versionadded`, `versionchanged` and `deprecated`](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#paragraph-level-markup) to document these changes.

For the `psconvert` **-A** and **-I** changes, we may add a short description, like:

```
**-A**
Description of **-A** option.

.. versionchanged: 6.3.0
Modifies +m, +g, +p, et al. are moved to the **-I** option.

**-I**
Description of **-I** option.

.. versionchanged: 6.3.0
Add modifies +m, +g, +p, et al.
```

Such change history is definitely more useful than the changelog for each release.

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.