我讨厌reST,但喜欢Sphinx。是否有一种方法,狮身人面像读取Markdown而不是reStructuredText?
当前回答
这是对推荐方法的更新。
pip install recommonmark
我个人使用Sphinx 3.5.1,所以
# for Sphinx-1.4 or newer
extensions = ['recommonmark']
点击这里查看官方文件。
其他回答
这是对推荐方法的更新。
pip install recommonmark
我个人使用Sphinx 3.5.1,所以
# for Sphinx-1.4 or newer
extensions = ['recommonmark']
点击这里查看官方文件。
您可以在同一个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。查看这个答案的早期版本来找出答案。
我采纳了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。
这里有一个新的选择。MyST为Markdown添加了一些功能,允许Sphinx像rst一样构建文档。 https://myst-parser.readthedocs.io/en/latest/
推荐文章
- 证书验证失败:无法获得本地颁发者证书
- 当使用pip3安装包时,“Python中的ssl模块不可用”
- 无法切换Python与pyenv
- Python if not == vs if !=
- 如何从scikit-learn决策树中提取决策规则?
- 为什么在Mac OS X v10.9 (Mavericks)的终端中apt-get功能不起作用?
- 将旋转的xtick标签与各自的xtick对齐
- 为什么元组可以包含可变项?
- 如何合并字典的字典?
- 如何创建类属性?
- 不区分大小写的“in”
- 在Python中获取迭代器中的元素个数
- 解析日期字符串并更改格式
- 使用try和。Python中的if
- 如何在Python中获得所有直接子目录