使用帶有Markdown的sphinx而不是RST

Question

我討厭RST，但喜歡獅身人面像。 有沒有辦法讓sphinx讀取markdown而不是reStructuredText？

Answer 1

“正確”的方法是為markdown編寫docutils解析器 。 （另外還有Sphinx選項來選擇解析器。）這樣做的好處是可以立即支持所有的docutils輸出格式（但你可能不關心這一點，因為大多數類似的降價工具已經存在）。 如何在不從頭開發解析器的情況下接近它：

• 您可以作弊並編寫一個“解析器”，它使用Pandoc將markdown轉換為RST並將其傳遞給RST解析器:-)。

• 您可以使用現有的markdown-> XML解析器並將結果（使用XSLT？）轉換為docutils架構。

• 您可以使用一些現有的python markdown解析器 ，它允許您定義自定義渲染器並使其構建docutils節點樹。

• 您可以分叉現有的RST閱讀器，刪除與markdown無關的所有內容並更改不同的語法（ 這種比較可能會有所幫助）......
  編輯：我不推薦這條路線，除非你准備大量測試它。 Markdown已經有太多微妙的不同方言，這可能會導致另一個......

更新： https ： //github.com/sgenoud/remarkdown是docutils的降價閱讀器。 它沒有采用任何上述快捷方式，而是使用受peg-markdown啟發的Parsley PEG語法。 尚不支持指令。

更新： https ： //github.com/rtfd/recommonmark ，是ReadTheDocs原生支持的另一個docutils閱讀器。 源自remarkdown但使用CommonMark-py解析器。 不支持指令，但可以將或多或少自然的Markdown語法轉換為適當的結構，例如指向toctree的鏈接列表。 對於其他需求， ```eval_rst fenced block允許你嵌入任何rST指令。

---

在所有情況下，您都需要發明Markdown的擴展來表示Sphinx指令和角色 。 雖然你可能不需要所有這些，但有些像.. toctree::是必不可少的。
我認為這是最難的部分。 在Sphinx擴展之前，reStructuredText已經比降價更豐富了。 即使是大量擴展的降價，例如pandoc ，也主要是rST功能集的一個子集。 這需要很多支持！

在實現方面，最簡單的方法是添加一個通用構造來表達任何docutils角色/指令。 語法靈感的明顯候選者是：

• 屬性語法，pandoc和其他一些實現已經允許在許多內聯和塊結構中。 例如`foo`{.method} - > `foo`:method: 。
• HTML / XML。 從<span class="method">foo</span>到只插入docutils內部XML的kludgiest方法！
• 指令的某種YAML？

但是這樣的通用映射不會是最降價十歲上下的解決方案。目前最活躍的地方，討論降價擴展是https://groups.google.com/forum/#!topic/pandoc-discuss ， https：//開頭github.com/scholmd/scholmd/

這也意味着你不能只重復使用markdown解析器而不以某種方式擴展它。 通過支持定制過濾器， Pandoc再次辜負了瑞士軍刀的文件轉換聲譽 。 （事實上​​，如果我接近這個，我會嘗試在docutils讀者/變換器/編寫器和pandoc讀取器/過濾器/編寫器之間建立一個通用的橋梁。它比你需要的更多，但是收益會比sphinx /更寬降價。）

---

另類瘋狂的想法：不是擴展markdown來處理Sphinx，而是擴展reStructuredText來支持（主要）markdown的超集！ 美麗的是你將能夠按原樣使用任何Sphinx功能，但能夠在降價時寫出大部分內容。

已經有相當多的語法重疊 ; 最值得注意的是鏈接語法是不兼容的。 我想如果你為RST添加對markdown鏈接和### -style標題的支持，並將默認的`backticks`角色更改為literal，並且可能會將縮進塊更改為literal（RST支持> ... for nowations nowdays），你會得到一些可以支持大多數降價的東西。

Answer 2

您可以在同一個Sphinx項目中使用Markdown和reStructuredText。 閱讀文檔簡明扼要地記錄了如何做到這一點。

安裝Recommonmark（ pip install recommonmark ）然后編輯conf.py ：

from recommonmark.parser import CommonMarkParser

source_parsers = {
    '.md': CommonMarkParser,
}

source_suffix = ['.rst', '.md']

---

我在Github上創建了一個小例子項目（serra / sphinx-with-markdown），展示了它的工作原理。 它使用CommonMark 0.5.4和Recommonmark 0.4.0。

Answer 3

這不使用Sphinx，但MkDocs將使用Markdown構建您的文檔。 我也討厭第一個，到目前為止真的很喜歡MkDocs。

Answer 4

更新：現在官方支持並記錄在sphinx文檔中 。

它看起來像一個基本的實現已經進入了Sphinx的方式但是還沒有結束。 請參閱github問題評論

安裝依賴項：

pip install commonmark recommonmark

調整conf.py ：

source_parsers = {
    '.md': 'recommonmark.parser.CommonMarkParser',
}
source_suffix = ['.rst', '.md']

Answer 5

Markdown和ReST做了不同的事情。

RST提供了處理文檔的對象模型。

Markdown提供了一種雕刻文本的方法。

想要從您的sphinx項目中引用您的Markdown內容，使用RST來划分整個信息架構和更大文檔的流程似乎是合理的。 讓markdown做它做的事情，這允許作家專注於寫文本。

有沒有辦法引用降價域，只是按原樣雕刻內容？ RST / sphinx似乎已經處理了像toctree這樣的功能而沒有在markdown中復制它們。

Answer 6

我和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(' '))

Answer 7

現在官方支持： http ： //www.sphinx-doc.org/en/stable/markdown.html

Answer 8

有一個解決方法。
sphinx-quickstart.py腳本生成一個Makefile。
每次要生成文檔時，都可以從Makefile輕松調用Pandoc，以便將Markdown轉換為reStructuredText。

Answer 9

請注意，以下maven插件完全支持使用maven和嵌入式Sphinx + MarkDown支持構建文檔：

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>