Document option changes in the HTML documentation

[seisman]

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 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.

[seisman]

An alternative way is having a "Changelog" section at the end of each module page. For example, at the end of the psconvert page, we can have:

Changes
=======

- 6.3.0: Modifiers +m, +g et al of **-A** option are moved to **-I** option. (#5583)

[seisman]

Ping @PaulWessel @joa-quim @meghanrjones for comments.

[PaulWessel]

I think it is a good idea, @seisman. I wonder how far back you wanted to go (quite a bit relative to 4, and we may struggle to find the info).

[seisman]

I don't think we should spend the time finding all the old changes. Instead, we can just start to document the changes since now (or since 6.2.0).

We can also add the old changes like the one reported in #5644, but we don't have to.

[maxrjones]

Good idea. I agree with starting with changes since 6.2.0.

I am not sure if the rate of deprecation since I started in Nov is representative, but based on what I have observed I would prefer a Deprecation section for each module rather than individual notices for each option to avoid making the documentation too cluttered. If it were a changes section, I would expect new modifiers and arguments to be included which is not necessary.

This will be more helpful if people know what version the script was made with. What do you think about including the current version in the output from gmt --new-script?

[seisman]

This will be more helpful if people know what version the script was made with. What do you think about including the current version in the output from gmt --new-script?

Sounds a good idea.

I would prefer a Deprecation section for each module rather than individual notices for each option to avoid making the documentation too cluttered. If it were a changes section, I would expect new modifiers and arguments to be included which is not necessary.

Yes, I agree. A "Deprecation" section means less work for us but still useful to users.

[seisman]

I'm reopening the issue, because I think we still need to discuss whether we need to follow this way to document changes and deprecations for each module. We already documented the changes in https://docs.generic-mapping-tools.org/dev/changes.html and users may read it when they see the announcement of a new release and then forget everything.

If we decide to document the changes/deprecations in the module manpage, we should start to do it since v6.5.0.

[Esteban82]

I was just looking at a comand used for GMTSAR ( grdblend filelist -R-69/-68/-55/-54 -I1c -N0 -Gall.grd). In the 6.5 version there is no info about -N0 and for c in (-I1c).

I don't find very useful to see the changelog. So, I think it is better to have a changes/deprecations in the module manpage.

An alternative would be to say the users to see older versions of the documentation. I found it helpful and would less work for us.

[PaulWessel]

Yes, it is a bit messy. While deprecating -N is relatively new (code comment says 7.29.2021 PW, use -di), we have not used c for seconds since the Clinton administration. It has been s for a long time. I bet GMTSAR csh scripts have lots of old GMT syntax lurking around.

[seisman]

An alternative would be to say the users to see older versions of the documentation. I found it helpful and would less work for us.

There are too many old versions (6.3, 6.2, 6.1, 6.0 and 5.4). Users may have no idea when an option was changed.

BTW, documenting the option changes also helps GMT wrappers like PyGMT to track the changes in GMT.

[PaulWessel]

I think clearly the best scheme is for the most current module doc version to have a section at the end on deprecation. Might we add

.. include:: blockmean_deprecated.rst_

at the end of blockmean.rst and similarly for all modules? Most might be empty since I assume the file must exist for sphinx (?).
That way, we just need to remember to add note to the corresponding file when we deprecate an option. As versions move on the previous version will still have deprecation notices but the most recent version may have those and newer ones.

[seisman]

I don't understand why we need files like blockmean_deprecated.rst_.

The idea in my mind is: in the release changes page, we only list changes about newly added modules and changes in core syntax (e.g., changes in -B). For any module-specific changes, we can simply list them in the changelog section at the end of each module manpage.

[PaulWessel]

OK, I was thinking of some auto-generated thing: Build those include files (or empty) from special comments in the source C files. But maybe not worth my time.

[Esteban82]

There are too many old versions (6.3, 6.2, 6.1, 6.0 and 5.4). Users may have no idea when an option was changed.

They could start by the oldest one. It is very easy to change between those versions.