Migrate all ReST files to Markdown formats

[seisman]

Sphinx has supported both ReST and Markdown formats for a long time. Apparently, ReST is much complex than Markdown. It would be easier for us to update and maintain the website if we convert .rst files to .md files.

[anbj]

Do you know of an automated way of doing this?

I guess you could argue that this be done for the GMT docs as well.

[joa-quim]

I hear that Markdown is also more limited than RsT. Does it worth the risk?

[seisman]

MyST markdown is almost as powerful as ReST. It even can use raw ReST directives. See https://mystmd.org/ for more information.

Actually the GMT Chinese documentation has migrated most its content (except the manpages for GMT modules) from ReST to Markdown (see PR gmt-china/GMT_docs#1346, but the PR comments were written in Chinese)

[anbj]

Did you convert from ReST to MyST by hand?

[seisman]

We used the rst2myst tool (https://github.com/executablebooks/rst-to-myst). It usually works well but is not ideal, so manual fixes are needed. Please see our experience at gmt-china/GMT_docs#1344 (comment) (again in Chinese )

[anbj]

Thanks!

[Esteban82]

It would be easier for us to update and maintain the website if we convert .rst files to .md files.

I trust your word that it's worth doing.