web-dev-qa-db-ja.com

RSTの代わりにMarkdownでスフィンクスを使用する

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

pythonmarkdownpython-sphinx
195
digi604

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

  • Pandoc を使用してマークダウンをRSTに変換し、それをRSTパーサーに渡す「パーサー」をごまかすことができます:-)。

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

  • 既存の python markdown parser を使用すると、カスタムレンダラーを定義して、ドキュチルノードツリーを構築できます。

  • 既存のRSTリーダーをフォークして、マークダウンに関係のないすべてを削除し、さまざまな構文を変更できます（ この比較 が役立つ場合があります）...
    編集：徹底的にテストする準備がない限り、このルートはお勧めしません。 Markdownにはすでに微妙に異なる方言が多すぎますが、これはおそらくもう一つの方言になるでしょう...

UPDATE：https://github.com/sgenoud/remarkdown は、docutilsのマークダウンリーダーです。上記のショートカットは使用しませんでしたが、 peg-markdown に触発された Parsley PEG文法を使用します。 まだディレクティブをサポートしていません 。

更新： https://github.com/rtfd/recommonmark これは別のdocutilsリーダーであり、ReadTheDocsでネイティブにサポートされています。remarkdownから派生しましたが、 CommonMark-py パーサーを使用します。ディレクティブをサポートしていませんが、 は多かれ少なかれ自然なMarkdown構文を適切な構造に変換できます 。 toctreeへのリンクのリスト。他のニーズについては、 ```eval_rst fenced block を使用すると、rSTディレクティブを埋め込むことができます。

allの場合、Markdownの拡張を考案して Sphinxディレクティブとロールを表現する必要があります 。これらのすべてが必要なわけではありませんが、.. toctree::のようなものが不可欠です。
これが最も難しい部分だと思います。 Sphinx拡張の前のreStructuredTextは、すでにmarkdownよりもリッチでした。 pandoc's などの大幅に拡張されたマークダウンでさえ、ほとんどが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は、 custom filtes をサポートすることにより、ドキュメント変換のスイスアーミーナイフとしての評判に再び応えています。 （実際、私がこれに近づくとしたら、docutilsリーダー/トランスフォーマー/ライターとpandocリーダー/フィルター/ライターの間に一般的な橋を架けようとします。マークダウン。）

別のクレイジーなアイデア：Sphinxを処理するためにマークダウンを拡張する代わりに、reStructuredTextを拡張して（ほとんど）マークダウンのスーパーセットをサポートします！ Sphinxのすべての機能をそのまま使用でき、しかもほとんどのコンテンツをマークダウンで記述できるのが魅力です。

すでにかなりの構文オーバーラップがあります;最も顕著なのは、リンク構文に互換性がないことです。マークダウンリンクと###- styleヘッダーのサポートをRSTに追加し、デフォルトの`backticks`ロールをリテラルに変更し、インデントされたブロックをリテラルを意味するように変更すると（RSTは> ...今日の見積もりでは、ほとんどのマークダウンをサポートする有用なものが得られます。

91
Beni Cherniavsky-Paskin

同じ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']

私は小さなサンプルプロジェクトを作成しました Github（serra/sphinx-with-markdown）で どのように（そしてそれが）動作するかを示しています。 CommonMark 0.5.4とrecommonmark 0.4.0を使用します。

77
Marijn

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

28
jkmacc

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

基本的な実装がSphinxに組み込まれたように見えますが、Wordはまだ実行されていません。 github issueのコメントを参照

依存関係のインストール：

pip install commonmark recommonmark

調整conf.py：

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

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

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

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

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

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

21
bewest

私は、このタスクにpandocを使用するというBeniの提案に従いました。次のスクリプトをインストールすると、ソースディレクトリ内のすべてのマークダウンファイルが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(' '))
8
igniteflow

これは現在公式にサポートされています： http://www.sphinx-doc.org/en/stable/markdown.html

7
Clément

回避策があります。
sphinx-quickstart.pyスクリプトはMakefileを生成します。
MarkdownをreStructuredTextに変換するために、ドキュメントを生成するたびにMakefileからPandocを簡単に呼び出すことができます。

1
the_drow

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>
0
Donatello