我讨厌reST,但喜欢Sphinx。是否有一种方法,狮身人面像读取Markdown而不是reStructuredText?


当前回答

这是对推荐方法的更新。

pip install recommonmark

我个人使用Sphinx 3.5.1,所以

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

点击这里查看官方文件。

其他回答

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

这里有一个新的选择。MyST为Markdown添加了一些功能,允许Sphinx像rst一样构建文档。 https://myst-parser.readthedocs.io/en/latest/

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

我采纳了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(' '))

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

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