doc: Convert README from ReST to Markdown by yvonnefroehlich · Pull Request #3059 · GenericMappingTools/pygmt

yvonnefroehlich · 2024-02-20T16:27:00Z

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 · 2024-02-21T02:16:27Z

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 \

README.md

…ert-readme-rst2md

doc/maintenance.md

yvonnefroehlich · 2024-02-21T22:22:22Z

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.

This reverts commit 649e0a2.

yvonnefroehlich · 2024-02-23T14:43:11Z

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 · 2024-02-24T02:49:51Z

Do other mirrors work?

MarcoSal · 2024-02-24T10:32:30Z

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 · 2024-02-24T20:50:18Z

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

seisman · 2024-02-25T02:23:09Z

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 · 2024-02-25T05:03:57Z

doc/index.rst

+.. include:: ../README.md
    :start-after: doc-index-start-after
    :end-before: doc-index-end-before


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

```

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

GitHub Website

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

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

I've done this in commit 514420a.

Thanks @seisman for doing this and completing this PR.

Co-authored-by: Dongdong Tian <seisman.info@gmail.com>

seisman · 2024-02-26T05:47:18Z

doc/maintenance.md

 ### Check the README Syntax

-GitHub is a bit forgiving when it comes to the RST syntax in the README but PyPI is not.
+GitHub is a bit forgiving when it comes to the syntax in the README but PyPI is not.
 To check the README syntax, visit the
 [PyGMT TestPyPI release history](https://test.pypi.org/project/pygmt/#history), select
 the latest commit, and review the left sidebar and project description for any errors.


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.

Done in 1342678.

Convert README from rst to md

f10a118

yvonnefroehlich added the maintenance Boring but important stuff for the core devs label Feb 20, 2024

yvonnefroehlich added this to the 0.12.0 milestone Feb 20, 2024

yvonnefroehlich mentioned this pull request Feb 20, 2024

Convert documentation source files from ReStructuredText to Markdown #2928

Closed

3 tasks

yvonnefroehlich changed the title ~~doc: Convert README from ReStructuredText to Markdown~~ doc: Convert README from ReST to Markdown Feb 20, 2024

Fix link to image

b746198

seisman reviewed Feb 21, 2024

View reviewed changes

README.md Outdated Show resolved Hide resolved

README.md Outdated Show resolved Hide resolved

README.md Outdated Show resolved Hide resolved

seisman mentioned this pull request Feb 21, 2024

Policy for minimum supported GMT versions #2967

Closed

yvonnefroehlich added 8 commits February 21, 2024 09:33

Merge remote-tracking branch 'origin/convert-readme-rst2md' into conv…

2e55cd7

…ert-readme-rst2md

Adjust line length and indent

db54a51

Aujust link in index

3360f45

Update maintenance

7be24c3

Update further files

a68367c

Remove blank line

429cf87

Use consistent lower-case letters in headings

0137ffe

Fix

d85c73e

yvonnefroehlich commented Feb 21, 2024

View reviewed changes

doc/maintenance.md Outdated Show resolved Hide resolved

yvonnefroehlich and others added 4 commits February 21, 2024 23:52

Add start and end points

1d42600

Try with out start and end points

649e0a2

Revert "Try with out start and end points"

f7cb90a

This reverts commit 649e0a2.

Merge branch 'main' into convert-readme-rst2md

c7b8433

Improve text

84b5236

seisman reviewed Feb 25, 2024

View reviewed changes

yvonnefroehlich and others added 6 commits February 25, 2024 14:31

Include markdown file in rst file

ad5d34b

Co-authored-by: Dongdong Tian <seisman.info@gmail.com>

Merge branch 'main' into convert-readme-rst2md

03b67c6

Convert the index file from ReST to Markdown

514420a

Fix

2cb66fb

One more fix

4cdf6f7

Ignore some Sphinx warnings

c10fcfe

seisman reviewed Feb 26, 2024

View reviewed changes

seisman added 4 commits February 26, 2024 15:47

Remove the section about checking the README syntax

1342678

Update README.rst/README.md to README in changes.md

04c66cd

Merge branch 'main' into convert-readme-rst2md

debeba9

Minor fix

7d4b9c7

seisman approved these changes Feb 26, 2024

View reviewed changes

seisman added the final review call This PR requires final review and approval from a second reviewer label Feb 26, 2024

michaelgrund approved these changes Feb 26, 2024

View reviewed changes

seisman merged commit d2e0c08 into main Feb 27, 2024

seisman deleted the convert-readme-rst2md branch February 27, 2024 00:37

seisman added skip-changelog Skip adding Pull Request to changelog and removed final review call This PR requires final review and approval from a second reviewer labels Feb 27, 2024

Conversation

yvonnefroehlich commented Feb 20, 2024 • edited by seisman Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

seisman commented Feb 21, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

yvonnefroehlich commented Feb 21, 2024

Uh oh!

yvonnefroehlich commented Feb 23, 2024

Uh oh!

seisman commented Feb 24, 2024

Uh oh!

MarcoSal commented Feb 24, 2024

Uh oh!

yvonnefroehlich commented Feb 24, 2024

Uh oh!

seisman commented Feb 25, 2024

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

yvonnefroehlich commented Feb 20, 2024 •

edited by seisman

Loading

seisman commented Feb 21, 2024 •

edited

Loading