Using Sphinx with Markdown instead of reST
markdown, python, python-sphinx
Solution
You can use Markdown and reStructuredText in the same Sphinx project. How to do this is succinctly documented in the Sphinx documentation.
Install `myst-parser` (`pip install myst-parser`) and then edit `conf.py`:
# simply add the extension to your list of extensions
extensions = ['myst_parser']
source_suffix = ['.rst', '.md']
I've created a small example project on Github (serra/sphinx-with-markdown) demonstrating how (and that) it works. It uses Sphinx version 3.5.4 and myst-parser version 0.14.0.
In fact, MyST parser allows you to write your entire Sphinx documentation in Markdown. It supports directives and has several extensions you can enable through configuration in conf.py.
MyST parser requires Sphinx 2.1 or later. For earlier versions of Sphinx, you could use Markdown in Sphinx using recommonmark. Checkout earlier revisions of this answer to find out how.
Problem
I hate reST but love Sphinx. Is there a way that Sphinx reads Markdown instead of reStructuredText?