-
Notifications
You must be signed in to change notification settings - Fork 224
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
Comments
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
Thus, I am wondering whether PyPI expects ReStructuredText or there are some issues with Markdown. |
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.
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/). |
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. |
Done in #3056.
@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:
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. |
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:I think at least the following three files should be converted to markdown:
README.rst
doc: Convert README from ReST to Markdown #3059doc/install.rst
doc: Convert the installation guides source code from ReST to Markdown #2992doc/overview.rst
doc: Convert overview source code from ReST to Markdown #2953Comments?
The text was updated successfully, but these errors were encountered: