您可以在同一个Sphinx项目中使用Markdown和reStructuredText。 如何做到这一点在Sphinx文档中有简要的说明。

安装myst-parser (pip Install myst-parser)然后编辑conf.py:

# simply add the extension to your list of extensions
extensions = ['myst_parser']

source_suffix = ['.rst', '.md']

我在Github上创建了一个小的示例项目(serra/sphinx with-markdown)，演示它是如何工作的。它使用Sphinx 3.5.4版本和myst-parser 0.14.0版本。

事实上，MyST解析器允许您用Markdown编写整个Sphinx文档。它支持指令，并有几个扩展，你可以通过conf.py中的配置来启用。

MyST解析器要求Sphinx 2.1或更高版本。对于Sphinx的早期版本，可以使用推荐标记在Sphinx中使用Markdown。查看这个答案的早期版本来找出答案。

这是对推荐方法的更新。

pip install recommonmark

我个人使用Sphinx 3.5.1，所以

# for Sphinx-1.4 or newer
extensions = ['recommonmark']

点击这里查看官方文件。

请注意，使用maven和嵌入式Sphinx + MarkDown支持构建文档完全由以下maven插件支持:

https://trustin.github.io/sphinx-maven-plugin/index.html

<plugin>
  <groupId>kr.motd.maven</groupId>
  <artifactId>sphinx-maven-plugin</artifactId>
  <version>1.6.1</version>
  <configuration>
    <outputDirectory>${project.build.directory}/docs</outputDirectory>
  </configuration>
  <executions>
    <execution>
      <phase>package</phase>
      <goals>
        <goal>generate</goal>
      </goals>
    </execution>
  </executions>
</plugin>

有解决方法 sphinx-quickstart.py脚本生成一个Makefile。 每次您想要生成文档以将Markdown转换为reStructuredText时，都可以轻松地从Makefile调用Pandoc。

现在正式支持:http://www.sphinx-doc.org/en/stable/markdown.html

也见https://myst-parser.readthedocs.io/en/latest/syntax/optional.html的扩展，包括linkify使url自动链接。

这没有使用Sphinx，但是MkDocs将使用Markdown构建您的文档。我也讨厌rst，到目前为止我真的很喜欢MkDocs。