doc: Convert README from ReST to Markdown

[yvonnefroehlich]

Description of proposed changes

This PR converts the REAMDE from ReStructuredText to Markdown.

• Use pandoc to convert to markdown
• Make manual adjustments
• Fix image
• Update files
• Fix appearance on webpage
  Adding .. doc-index-start-after and .. doc-index-end-before does not work correctly. We have to look for the corresponding Markdown syntax

Preview:

• GitHub
  • ReST (old): https://github.com/GenericMappingTools/pygmt/blob/main/README.rst
  • Markdown (new): https://github.com/GenericMappingTools/pygmt/tree/convert-readme-rst2md?tab=readme-ov-file#pygmt
• Website
  • ReST (old): https://www.pygmt.org/dev/index.html
  • Markdown (new): https://pygmt-dev--3059.org.readthedocs.build/en/3059/

Fixes #2928

Reminders

• Run make format and make check to make sure the code follows the style guide.
• Add tests for new features or tests that would have caught the bug that you're fixing.
• Add new public functions/methods/classes to doc/api/index.rst.
• Write detailed docstrings for all functions/methods.
• If wrapping a new module, open a 'Wrap new GMT module' issue and submit reasonably-sized PRs.
• If adding new functionality, add an example to docstrings or tutorials.
• Use underscores (not hyphens) in names of Python files and directories.

Slash Commands

You can write slash commands (/command) in the first line of a comment to perform
specific operations. Supported slash command is:

• /format: automatically format and lint the code

[seisman]

README.rst is hard-coded in many files. Need to update README.rst to README.md in all these files:

pyproject.toml:8:readme = "README.rst"
doc/maintenance.md:225:9. Refresh citation information. Specifically, the BibTeX in `README.rst` and
doc/index.rst:13:.. include:: ../README.rst
.github/workflows/ci_docs.yml:26:      - 'README.rst'
.github/workflows/ci_docs.yml:35:      - 'README.rst'
.github/workflows/publish-to-pypi.yml:27:      - 'README.rst'
.readthedocs.yaml:24:              README.rst \

[yvonnefroehlich]

README.rst is hard-coded in many files. Need to update README.rst to README.md in all these files:

pyproject.toml:8:readme = "README.rst"
doc/maintenance.md:225:9. Refresh citation information. Specifically, the BibTeX in `README.rst` and
doc/index.rst:13:.. include:: ../README.rst
.github/workflows/ci_docs.yml:26:      - 'README.rst'
.github/workflows/ci_docs.yml:35:      - 'README.rst'
.github/workflows/publish-to-pypi.yml:27:      - 'README.rst'
.readthedocs.yaml:24:              README.rst \

Thanks for posting this list! These files should be updated in the commits 3360f45, 7be24c3, and a68367c.

[yvonnefroehlich]

Currently building the documentation fails and the issue seem to be related to downloading the GMT remote datasets:

    pygmt.exceptions.GMTCLibError: Module 'grdcut' failed with status code 72:
    grdcut [ERROR]: Remote download is currently deactivated
    grdcut [ERROR]: Unable to obtain remote file @earth_relief_10m_g

Is there currently any maintenance regarding the remote datasets and they are temporarily not available?
This issue is also reported in #3063.

[seisman]

Do other mirrors work?

[MarcoSal]

Currently building the documentation fails and the issue seem to be related to downloading the GMT remote datasets:

    pygmt.exceptions.GMTCLibError: Module 'grdcut' failed with status code 72:
    grdcut [ERROR]: Remote download is currently deactivated
    grdcut [ERROR]: Unable to obtain remote file @earth_relief_10m_g

Is there currently any maintenance regarding the remote datasets and they are temporarily not available? This issue is also reported in #3063.

now it's working again. the service was probably under maintenance.

[yvonnefroehlich]

It looks like downloading the remote datasets works again and this was only a temporary issue.

[seisman]

• Fix appearance on webpage
  Adding .. doc-index-start-after and .. doc-index-end-before does not work correctly. We have to look for the corresponding Markdown syntax

Does the solution here
https://stackoverflow.com/questions/46278683/include-my-markdown-readme-into-sphinx/68005314#68005314 work for you?

[seisman]

Suggested change

	.. include:: ../README.md
	:start-after: doc-index-start-after
	:end-before: doc-index-end-before
	```{include} ../README.md
	:start-after: doc-index-start-after
	:end-before: doc-index-end-before
	```

[yvonnefroehlich]

I tried this idea, but unfortunately, this also does not work:

GitHub	Website

[seisman]

perhaps you have to convert index.rst to index.md

[yvonnefroehlich]

I will try this, but I will be quite busy in the next three weeks. Thus, I am not sure if I will have the time to do this in the next days 🙁.

[seisman]

I've done this in commit 514420a.

[yvonnefroehlich]

Thanks @seisman for doing this and completing this PR.

[seisman]

https://packaging.python.org/en/latest/guides/making-a-pypi-friendly-readme/#creating-a-readme-file

PyPI uses the GitHub Flavored Markdown syntax by default, so we no longer need to check the README syntax on PyPI.

[seisman]

Done in 1342678.