Sorry if this has already been covered; I searched for a previous discussion and found none.
I’m wondering what the current thinking is on .md versus .rst files for package documentation. Markdown seems more popular at first glance, but reStructuredText seems to have more Python-specific tool support, including the ability to embed it in code documentation and publish on sites like readthedocs.
I’m not really looking to debate this topic; I just would like to know what’s considered best practice (if it exists).
I would frame the discussion as reStructuredText vs Markdown instead of Sphinx, since the last is a documentation tool, while the former two are languages. Also Sphinx technically has Markdown support
The official Python documentation uses reStructuredText (and actually backed by Sphinx), but the reason is at least partly because it predates Markdown. reStructuredText is still the default choice for package documentation AFAICT, but Markdown (with either Sphinx or tools like MkDocs) is not unpopular either. I’d say both are good practices, you can choose which ever you feel more comfortable with.
Personally I prefer reStructuredText for package documentation. Markdown is very good, but is too simplistic for this particular purpose. reStructuredText is a big winner when it comes to extendibility, and makes my documentation much cleaner and maintainable. I strongly recommend learning reStructuredText; you milage may vary, but it would be worthwhile to at least try it first.
If you aren’t sure, I’d go with ReST+Sphinx. Other options have technical merits too, but sphinx is overwhelmingly more popular in the Python package ecosystem, so you’ll just find more tooling and extensions, when you run into a problem you’re more likely to find documented workarounds, etc.
On different projects that I maintain, some use reStructuredText and others use Markdown for package documentation. They are both widely used.
When working on Documentation, both are worthwhile to know. pandoc is a tool that can be used to convert between formats. It’s not perfect but pandoc is a good first pass if translating from one format to another.
For packaging docs, I would give the edge to reStructuredText, but Markdown is a reasonable option too. I believe the packaging docs cover both formats.
