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


当前回答

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

其他回答

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自动链接。

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

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

这是对推荐方法的更新。

pip install recommonmark

我个人使用Sphinx 3.5.1,所以

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

点击这里查看官方文件。