我讨厌reST,但喜欢Sphinx。是否有一种方法,狮身人面像读取Markdown而不是reStructuredText?
当前回答
2021年5月更新:推荐标记已弃用,取而代之的是神秘解析器(感谢astrojuanlu)
更新:现在sphinx文档正式支持并记录了这一点。
看起来它的基本实现已经进入了Sphinx,但还没有消息传出去。见github问题评论
安装的依赖关系:
pip install commonmark recommonmark
调整conf.py:
source_parsers = {
'.md': 'recommonmark.parser.CommonMarkParser',
}
source_suffix = ['.rst', '.md']
其他回答
我采纳了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(' '))
Markdown和ReST做不同的事情。
RST为处理文档提供了一个对象模型。
Markdown提供了一种雕刻文本的方法。
从您的sphinx项目中引用Markdown内容,使用RST来stub出一个较大文档的整体信息架构和流程,这似乎是合理的。让markdown发挥它的作用,让作者专注于写作文本。
是否有一种方法来引用markdown域,只是按原样雕刻内容?RST/sphinx似乎已经解决了像toctree这样的特性,而没有在markdown中复制它们。
现在正式支持:http://www.sphinx-doc.org/en/stable/markdown.html
也见https://myst-parser.readthedocs.io/en/latest/syntax/optional.html的扩展,包括linkify使url自动链接。
有解决方法 sphinx-quickstart.py脚本生成一个Makefile。 每次您想要生成文档以将Markdown转换为reStructuredText时,都可以轻松地从Makefile调用Pandoc。
这里有一个新的选择。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中获得所有直接子目录