Move the long "Compatibility" table to a separate file

[seisman]

The "Compatibility" table in the README file is a long table and is growing fast as we have a PyGMT release every three months.

I feel we can move the table to a separate file in the doc directory. We can still keep this section heading in the README file, but only write a simple sentence about the NEP 29 policy and link to the table.

[yvonnefroehlich]

The "Compatibility" table in the README file is a long table and is growing fast as we have a PyGMT release every three months. I feel we can move the table to a separate file in the doc directory.

I agree that this table became quite long in the meantime, and moving it to a separate file makes sense. Should we keep the reStructuredText (.rst) syntax or write a Markdown (.md) file?

We can still keep this section heading in the README file, but only write a simple sentence about the NEP 29 policy and link to the table.

Aside from the NEP 29 policy, I think we should give the minimum required GMT version for the last release.

[seisman]

Ping @weiji14 for comments since you were the one who proposed to add the compatibility table in #748.

[weiji14]

What about hiding it in a <details> </details> html tag while keeping it in the same file? We could also just show, say the 5 latest versions, and hide the others under <details>?

[seisman]

What about hiding it in a <details> </details> html tag while keeping it in the same file?

Not bad. Does it work in HTML documentation?

We could also just show, say the 5 latest versions, and hide the others under <details>?

It means we have to maintain two tables, and when we make a new release, we need to add the new release to table 1 and also move the oldest release from table 1 to table 2.

[weiji14]

What about hiding it in a <details> </details> html tag while keeping it in the same file?

Not bad. Does it work in HTML documentation?

Not sure about HTML, maybe open a PR to see? I just tried it quickly with the preview, and it seems to work

Note thought that since this is reStructuredText, we need to do:

.. raw:: html

   <details>

following https://stackoverflow.com/questions/2454577/sphinx-restructuredtext-show-hide-code-snippets

We could also just show, say the 5 latest versions, and hide the others under <details>?

It means we have to maintain two tables, and when we make a new release, we need to add the new release to table 1 and also move the oldest release from table 1 to table 2.

Yeah, reSt tables are a bit annoying. Maybe we could convert to markdown first? I see more people using MyST with Sphinx now - https://myst-parser.readthedocs.io/en/v0.15.1/sphinx/intro.html#get-started-with-myst-in-sphinx

[seisman]

I still prefer to move the compatibility table to a separate file, mainly because (1) it's rare to have a compatibility table in a README file (didn't see it in pandas, xarray and scipy); (2) most users don't care about the compatibility table because mamba/conda/pip already take care of version dependencies.

[weiji14]

Ok, let's move the compatibility table to another location then. The table was more important in earlier versions of PyGMT when we bumped the minimum required GMT version more often, but now that we maintain backwards compatibility to GMT 6.3, users should be ok with a range of versions.

[yvonnefroehlich]

I just started working on this in PR #2862. So far I kept the reSt syntax and just copied the compatibility table to a new file. Or do we want to convert the table to Markdown?

[seisman]

Or do we want to convert the table to Markdown?

Ideally yes, but to write the table in Markdown, we will have very long lines like below, which maybe more difficult to maintain.

| `v0.10.0 <https://github.com/GenericMappingTools/pygmt/releases/tag/v0.10.0>`_ (latest release) | `v0.10.0 Documentation <https://www.pygmt.org/v0.10.0>`_ | >=6.3.0 | >=3.9 | >=1.22 |