Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Convert documentation source files from ReStructuredText to Markdown #2928

Closed
3 tasks done
seisman opened this issue Dec 28, 2023 · 6 comments · Fixed by #3059
Closed
3 tasks done

Convert documentation source files from ReStructuredText to Markdown #2928

seisman opened this issue Dec 28, 2023 · 6 comments · Fixed by #3059
Labels
maintenance Boring but important stuff for the core devs
Milestone

Comments

@seisman
Copy link
Member

seisman commented Dec 28, 2023

Currently, some documentations are written in Markdown while some are in ReStructuredText. I think it's better to use a consistent format so that new contributors won't be confused.

Here are the .rst files in the repository:

$ find . -name '*.rst'
./README.rst
./doc/install.rst
./doc/overview.rst
./doc/index.rst
./doc/api/index.rst
./doc/_templates/autosummary/module.rst
./doc/_templates/autosummary/class.rst
./doc/_templates/autosummary/exception.rst
./doc/_templates/autosummary/method.rst
./doc/_templates/autosummary/base.rst
./doc/_templates/autosummary/function.rst

I think at least the following three files should be converted to markdown:

Comments?

@seisman seisman added the discussions Need more discussion before taking further actions label Dec 28, 2023
@yvonnefroehlich
Copy link
Member

I agree that we should work towards using a consistent format (when possible).

Did people have specific reasons to use ReStructuredText for these files when writing them?

Regarding README.rst, we have this in the Maintainers Guide (https://www.pygmt.org/dev/maintenance.html#check-the-readme-syntax):

Check the README Syntax
GitHub is a bit forgiving when it comes to the RST syntax in the README, but PyPI is not. To check the README syntax, visit the PyGMT TestPyPI release history, select the latest commit, and review the left sidebar and project description for any errors.

Thus, I am wondering whether PyPI expects ReStructuredText or there are some issues with Markdown.

@seisman
Copy link
Member Author

seisman commented Dec 28, 2023

Did people have specific reasons to use ReStructuredText for these files when writing them?

These must be some historical reasons. If you're familiar with both ReST and Markdown, you will see that ReST is more powerful and is suitable for writing technical documentation for big projects. Instead, the original Markdown syntax is much simpler and is most suitable for writing short documentation like a blog post. However, in recent years, the MyST Markdown has been mature enough to be as powerful as ReST and is becoming popular.

Regarding README.rst, we have this in the Maintainers Guide (https://www.pygmt.org/dev/maintenance.html#check-the-readme-syntax):

Check the README Syntax
GitHub is a bit forgiving when it comes to the RST syntax in the README, but PyPI is not. To check the README syntax, visit the PyGMT TestPyPI release history, select the latest commit, and review the left sidebar and project description for any errors.

Thus, I am wondering whether PyPI expects ReStructuredText or there are some issues with Markdown.

PyPI started to support Markdown (https://packaging.python.org/en/latest/guides/making-a-pypi-friendly-readme/#creating-a-readme-file) since 2018 (https://blog.thea.codes/github-flavored-markdown-on-pypi/).

@yvonnefroehlich
Copy link
Member

yvonnefroehlich commented Jan 2, 2024

Maybe I will find the time to work on rewriting the README, as I am already working on moving the compatibility table to a separate file. In this context, we also discussed rewriting this table in Markdown (#2858 (comment) and #2858 (comment)).

@seisman seisman added maintenance Boring but important stuff for the core devs and removed discussions Need more discussion before taking further actions labels Jan 3, 2024
@seisman seisman added this to the 0.12.0 milestone Jan 3, 2024
@seisman
Copy link
Member Author

seisman commented Jan 3, 2024

Maybe I will find the time to work on rewriting the README, as I am already working on moving the compatibility table to a separate file. In this context, we also discussed rewriting this table in Markdown (#2858 (comment) and #2858 (comment)).

I think we need to address #2863 and #2858 before working on the README file.

@seisman
Copy link
Member Author

seisman commented Feb 19, 2024

In this context, we also discussed rewriting this table in Markdown (#2858 (comment) and #2858 (comment)).

Done in #3056.

Maybe I will find the time to work on rewriting the README, as I am already working on moving the compatibility table to a separate file.

@yvonnefroehlich Now we can start working on the README file. Let me know if you'd like to work on it. Just in case you didn't know yet, pandoc is a tool that can convert ReST to Markdown automatically. The command is:

pandoc README.rst -t markdown

Of course, after the pandoc conversion, you may still need to make some manual edits to make it better.

@yvonnefroehlich
Copy link
Member

Maybe I will find the time to work on rewriting the README, as I am already working on moving the compatibility table to a separate file.

@yvonnefroehlich Now we can start working on the README file. Let me know if you'd like to work on it. Just in case you didn't know yet, pandoc is a tool that can convert ReST to Markdown automatically. The command is:

pandoc README.rst -t markdown

Of course, after the pandoc conversion, you may still need to make some manual edits to make it better.

Thanks @seisman for pointing out this tool 🙂. I just started working on converting the REAMDE to markdown in PR #3059.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
maintenance Boring but important stuff for the core devs
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants