RSTの代わりにMarkdownでsphinxを使用する

私はRSTが嫌いですが、スフィンクスが大好きです。reStructuredTextの代わりにsphinxがmarkdownを読み取る方法はありますか？

これを行う「適切な」方法は、マークダウン用のdocutilsパーサーを作成することです。（さらに、パーサーを選択するためのSphinxオプション。）これの利点は、すべてのdocutils出力形式を即座にサポートできることです（ただし、ほとんどの場合、同様のマークダウンツールがすでに存在しているため、気にする必要はありません）。パーサーをゼロから開発せずにそれに取り組む方法：

1. Pandocを使用してマークダウンをRSTに変換し、それをRSTパーサーに渡す"パーサー"をカンニングして作成できます。

2. 既存のmarkdown-> XMLパーサーを使用して、結果を（XSLT？を使用して）docutilsスキーマに変換できます。

3. カスタムレンダラーを定義してdocutilsノードツリーを構築できるようにする既存のpythonマークダウンパーサーをいくつか使用できます。

4. あなたは、異なる構文をマークダウンし、変化に無関係なすべてのもの（リッピング、既存のRST読者をforkでき、この比較かもしれないのヘルプ）...
   EDITを：あなたは重く、それをテストするために用意しない限り、私はこのルートをお勧めしません。マークダウンにはすでに微妙に異なる方言が多すぎます。これはおそらくもう1つになります...

更新： https : //github.com/sgenoud/remarkdownは、docutilsのマークダウンリーダーです。上記のショートカットはありませんが、peg-markdownに触発されたパセリ PEG文法を使用します。

• ディレクティブはまだサポートされていません。

更新：https : //github.com/readthedocs/recommonmarkは、ReadTheDocsでネイティブにサポートされている別のdocutilsリーダーです。 remarkdownから派生しましたが、CommonMark-pyパーサーを使用しています。

• これは、変換することができます toctreeへのリンクの適切な構造例えばリストに特定多かれ少なかれ自然マークダウン構文を。*ロールの一般的なネイティブ構文はありません。
• ディレクティブを含むrSTコンテンツの埋め込みを、 fenced ```eval_rstブロックとディレクティブの省略形でサポートしますDIRECTIVE_NAME:: ...。

更新：MySTはさらに別のdocutins / Sphinxリーダーです。markdown-it-py、CommonMark互換に基づいています。

• {ROLE_NAME}`...`ロールの一般的な構文があります。
• ```{DIRECTIVE_NAME} ...フェンス付きブロックを使用したディレクティブの一般的な構文があります。

では、すべての例は、表現するためにMarkdown記法の拡張を考案する必要がありますスフィンクスディレクティブとロールを。それらのすべてが必要なわけではありませんが、のようなもの.. toctree::が不可欠です。
これが一番難しいと思います。Sphinx拡張機能がマークダウンよりも豊富になる前のreStructuredText。pandocのような大幅に拡張されたマークダウンでさえ、rST機能セットのサブセットです。それはカバーするべき多くの根拠です！

実装に関しては、最も簡単なことは、あらゆるdocutilsロール/ディレクティブを表現するための一般的な構成を追加することです。構文インスピレーションの明らかな候補は次のとおりです。

• pandocおよび他の一部の実装では、すでに多くのインラインおよびブロック構成で許可されている属性構文。たとえば`foo`{.method}-> `foo`:method:です。
• HTML / XML。から<span class="method">foo</span>docutils内部XMLを挿入するだけの最も扱いにくいアプローチに！
• ディレクティブ用のある種のYAML？

しかし、このような一般的なマッピングは、ほとんどのマークダウンっぽいソリューションではありません...現在値下げ拡張を議論するための最も活発な場所ですhttps://groups.google.com/forum/#!topic/pandoc-discuss、https：//でgithub.com/scholmd/scholmd/

これはまた、なんらかの方法で拡張せずにマークダウンパーサーを再利用できないことを意味します。Pandocは、カスタムフィルトをサポートすることにより、ドキュメント変換のスイスアーミーナイフとしての評判を再び満たしています。（実際、私がこれに近づくとしたら、私はdocutilsリーダー/トランスフォーマー/ライターとpandocリーダー/フィルター/ライターの間に一般的なブリッジを構築しようとします。それは必要以上ですが、スフィンクス/値下げ。）

代替クレイジーなアイデア：Sphinxを処理するためにマークダウンを拡張する代わりに、（ほとんど）マークダウンのスーパーセットをサポートするようにreStructuredTextを拡張します！優れている点は、Sphinxの機能をそのまま使用できる一方で、ほとんどのコンテンツをマークダウンで記述できることです。

すでにかなりの構文の重複があります。特にリンク構文には互換性がありません。マークダウンリンクと###スタイルヘッダーのサポートをRSTに追加し、デフォルトの`backticks`役割をリテラルに変更し、インデントされたブロックをリテラルを意味するように変更すると（RSTは> ...今日の引用をサポート）、ほとんどのマークダウンをサポートする使用可能なものになると思います。

MarkdownとreStructuredTextを同じSphinxプロジェクトで使用できます。これを行う方法は、Read The Docsに簡潔に文書化されています。

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を使用します。

これはSphinxを使用しませんが、MkDocsはMarkdownを使用してドキュメントを構築します。私も最初は嫌いで、これまでMkDocsを本当に楽しんでいます。

更新：これは正式にサポートされ、sphinx docsに文書化されています。

基本的な実装によってSphinxへの道が開かれたようですが、言葉はまだ定着していません。github issueコメントを参照してください

インストール依存関係：

pip install commonmark recommonmark

調整conf.py：

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

MarkdownとReSTは異なる処理を行います。

RSTは、ドキュメントを操作するためのオブジェクトモデルを提供します。

Markdownは、テキストの一部を刻む方法を提供します。

RSTを使用して全体的な情報アーキテクチャとより大きなドキュメントのフローをスタブ化するために、sphinxプロジェクトからMarkdownコンテンツのビットを参照したいのは理にかなっているようです。markdownがそれを行うようにします。これにより、ライターはテキストの書き込みに集中できます。

マークダウンドメインを参照して、コンテンツをそのまま彫刻する方法はありますか？RST / sphinxはtoctree、マークダウンでそれらを複製せずに機能を処理したようです。

これが正式にサポートされるようになりました：http : //www.sphinx-doc.org/en/stable/markdown.html

私はこの作業にパンドックを使用するというベニの提案に同意しました。次のスクリプトをインストールすると、ソースディレクトリ内のすべてのマークダウンファイルがrstファイルに変換されるため、すべてのドキュメントをマークダウンに書き込むことができます。これが他の人に役立つことを願っています。

#!/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-quickstart.pyスクリプトはMakefileを生成します。
MarkdownをreStructuredTextに変換するためにドキュメントを生成するたびに、MakefileからPandocを簡単に呼び出すことができます。

これが新しいオプションです。MySTはMarkdownにいくつかの機能を追加し、Sphinxがrstと同じようにドキュメントを作成できるようにします。 https://myst-parser.readthedocs.io/en/latest/

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>