我采纳了Beni的建议，使用pandoc来完成这项任务。安装后，下面的脚本将把源目录中的所有markdown文件转换为rst文件，这样您就可以用markdown编写所有文档。希望这对其他人有用。

#!/usr/bin/env python
import os
import subprocess

DOCUMENTATION_SOURCE_DIR = 'documentation/source/'
SOURCE_EXTENSION = '.md'
OUTPUT_EXTENSION = '.rst'

for _, __, filenames in os.walk(DOCUMENTATION_SOURCE_DIR):
    for filename in filenames:
        if filename.endswith('.md'):
            filename_stem = filename.split('.')[0]
            source_file = DOCUMENTATION_SOURCE_DIR + filename_stem + SOURCE_EXTENSION
            output_file = DOCUMENTATION_SOURCE_DIR + filename_stem + OUTPUT_EXTENSION
            command = 'pandoc -s {0} -o {1}'.format(source_file, output_file)
            print(command)
            subprocess.call(command.split(' '))

我推荐使用MyST Markdown。这是Markdown的一种风格，旨在引入reStructuredText的主要特性。MyST代表显著结构化文本，可以被认为是“带有Markdown的rST”。

MyST是CommonMark标准的超集，它被定义为通过markdown-it-py包对CommonMark进行的离散扩展的集合)。这意味着CommonMark语法可以与MyST一起开箱即用，但是如果您愿意，您也可以使用更多的语法特性。

MyST为reStructuredText中的几乎每个特性都提供了语法，并且针对完整的Sphinx测试套件进行了测试，以确保可以重新创建相同的功能。例如:

下面是如何在MyST中编写指令:

```{directivename} directive options
:key: value
:key2: value2

Directive content
```

这是你在《神秘岛》中如何编写角色的方法

Here's some text and a {rolename}`role content`

MyST Markdown的Sphinx解析器也有一些很好的Sphinx特有的特性，比如使用Markdown链接语法([some text](someelink))来处理Sphinx中的交叉引用。例如，你可以在MyST中定义一个标签，并引用它，像这样:

(my-label)=
# My header

Some text and a [cross reference](my-label).

对于一个更完整的MyST Markdown语法列表，一个很好的参考是Jupyter Book备考表，它有许多常见的文档需求和各自的MyST语法来完成它。(MyST是作为Jupyter Book的一个组件创建的，尽管从技术角度来看它是一个完全独立的项目)。

在Sphinx文档和ReadTheDocs文档中，MyST现在是Sphinx推荐的Markdown工具。

要将MyST解析器添加到Sphinx文档中，只需执行以下操作:

pip install myst-parser

在conf.py中添加:

extensions = [
  ...
  "myst_parser",
  ...
]

您的Sphinx文档现在将能够解析CommonMark markdown以及扩展的MyST markdown语法!请查看MyST文档以获取更多信息!

我希望这有助于澄清一些事情!

请注意，使用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>

我采纳了Beni的建议，使用pandoc来完成这项任务。安装后，下面的脚本将把源目录中的所有markdown文件转换为rst文件，这样您就可以用markdown编写所有文档。希望这对其他人有用。

#!/usr/bin/env python
import os
import subprocess

DOCUMENTATION_SOURCE_DIR = 'documentation/source/'
SOURCE_EXTENSION = '.md'
OUTPUT_EXTENSION = '.rst'

for _, __, filenames in os.walk(DOCUMENTATION_SOURCE_DIR):
    for filename in filenames:
        if filename.endswith('.md'):
            filename_stem = filename.split('.')[0]
            source_file = DOCUMENTATION_SOURCE_DIR + filename_stem + SOURCE_EXTENSION
            output_file = DOCUMENTATION_SOURCE_DIR + filename_stem + OUTPUT_EXTENSION
            command = 'pandoc -s {0} -o {1}'.format(source_file, output_file)
            print(command)
            subprocess.call(command.split(' '))

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

您可以在同一个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。查看这个答案的早期版本来找出答案。