使用獅身人面像與Markdown代替RST

Question

我討厭RST，但愛獅身人面像。有沒有一種方法讓獅身人面像讀取markdown而不是reStructuredText？

Answer 1

這樣做的「正確」方法是編寫docutils parser進行降價。 （加上一個獅身人面像選項來選擇解析器。）它的優點將是對所有docutils輸出格式的即時支持（但您可能並不在乎，因爲大多數類似的降價工具已經存在）。方式來處理，沒有從頭開始開發一個解析器：

• 你可以欺騙和編寫使用Pandoc到降價轉換爲RST並傳遞到RST分析器:-)一個「解析器」。

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

• 你可以拿一些existing python markdown parser，讓你定義一個自定義的渲染器，並使其構建docutils節點樹。

• 你可以用叉子叉現有RST讀者，剝開一切無關的降價和改變不同的語法（this comparison可能幫助）...
  編輯：除非你準備在很大程度上，我不建議這條路線測試它。降價已經有太多微妙的不同方言，這將有可能導致尚未另外一...

UPDATE：https://github.com/sgenoud/remarkdown是docutils的減價讀者。它沒有采取任何上述快捷方式，但使用了Parsley PEG語法，其靈感來源於peg-markdown。 Doesn't yet支持指令。

更新：https://github.com/rtfd/recommonmark是另一個docutils讀者，本地支持ReadTheDocs。派生自重新下載，但使用CommonMark-py解析器。不支持指令，但can convert或多或少自然的Markdown語法適用於合適的結構，例如指向toctree的鏈接列表。對於其他需求，```eval_rst fenced block可讓您嵌入任何rST指令。

---

在所有案件，你需要創造降價的擴展來表示Sphinx directives and roles。雖然你可能不需要所有這些，但有些像.. toctree::是必不可少的。
這是我認爲最難的部分。在獅身人面像擴展已經比標記更豐富之前，它是reStructuredText。即使大幅擴展降價，如pandoc's，也大多是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/

這也意味着你不能只重用降價解析器，但不以某種方式進行擴展。 Pandoc再次恪守其作爲文件轉換瑞士軍刀的聲譽，支持custom filtes。 （事實上​​，如果我想這樣做，我會嘗試在docutils讀者/變形記者/作者和pandoc讀者/過濾器/作者之間建立一個通用橋樑，這比你需要的要多，但是收益會比sphinx /降價）

---

替代瘋狂的想法：而不是擴大降價處理獅身人面像，延長reStructuredText的支持（主要是）降價的超集！美麗的是，你將能夠使用任何獅身人面像功能，但能夠用降價編寫大部分內容。

已經有considerable syntax overlap;最值得注意的是鏈接語法不兼容。我認爲，如果您爲RST減價鏈接和###風格的標題添加支持，並將默認的`backticks`角色更改爲文字，並且可能會將縮進的塊更改爲意思字面（現在RST支持> ...），您將獲得可用的支持大多數降價。

Answer 2

有一種解決方法。
sphinx-quickstart.py腳本生成一個Makefile。
您可以在每次想要生成文檔以便將Markdown轉換爲reStructuredText時從Makefile輕鬆調用Pandoc。

Answer 3

Markdown和ReST做不同的事情。

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

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

想要從sphinx項目中引用Markdown內容中的一些內容似乎是合理的，它使用RST來截取整個信息體系結構和更大文檔的流程。讓降價做它做的事情，這可以讓作家專注於撰寫文字。

有沒有辦法引用一個降價域，只是爲了雕刻內容？ RST /獅身人面像似乎已經照顧了諸如toctree之類的功能而沒有在減價中重複它們。

Answer 4

這不使用獅身人面像，但MkDocs將使用Markdown構建您的文檔。我也很討厭，到目前爲止，我真的很喜歡MkDocs。

Answer 5

我跟貝尼建議使用pandoc完成這個任務。安裝後，以下腳本會將源目錄中的所有降價文件轉換爲第一個文件，以便您可以用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 6

您可以在同一個Sphinx項目中使用Markdown和reStructuredText。如何在Read The Docs上簡潔地記錄這一點。安裝recommonmark（pip install recommonmark），然後編輯conf.py：

from recommonmark.parser import CommonMarkParser 

source_parsers = { 
    '.md': CommonMarkParser, 
} 

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

---

我創建了一個小例子項目on Github (serra/sphinx-with-markdown)展示它是如何（以及）的作品。它使用CommonMark 0.5.4和推薦0.4.0。

Answer 7

它看起來像一個基本的實現已經進入獅身人面像的方式，但字還沒有到位。 See github issue comment

安裝依賴：

pip install commonmark recommonmark 

調整conf.py：

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

Answer 8

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

Answer 9

注意，使用行家和嵌入式獅身人面像+降價支持建立文檔完全由後續支持荷蘭國際集團的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>