235

reST は嫌いですが、Sphinx は大好きです。Sphinx が reStructuredText の代わりに Markdown を読み取る方法はありますか?

4

12 に答える 12

104

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

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

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

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

  4. 既存の RST リーダーをフォークして、マークダウンに関係のないものをすべて取り除き、さまざまな構文を変更することができます (この比較が役立つ場合があります)...
    編集: 十分にテストする準備ができていない限り、このルートはお勧めしません。Markdown にはすでに微妙に異なる方言が多すぎて、これによりさらに別の方言が発生する可能性があります...

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

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

  • 特定の多かれ少なかれ自然な Markdown 構文を適切な構造 (toctree へのリンクのリストなど) に変換できます。* ロールの一般的なネイティブ構文がありません。
  • ディレクティブを含む任意のrST コンテンツの埋め込みを、```eval_rstフェンスで囲まれたブロックとディレクティブの短縮形でサポートしDIRECTIVE_NAME:: ...ます。

UPDATE : MySTは、もう 1 つの docutins/Sphinx リーダーです。markdown-it-py に基づいており、CommonMark と互換性があります。

  • {ROLE_NAME}`...`ロールの一般的な構文があります。
  • ```{DIRECTIVE_NAME} ...フェンスで囲まれたブロックを含むディレクティブの一般的な構文があります。

いずれの場合も、Sphinx のディレクティブとロールを表すには、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/

This also means you can't just reuse a markdown parser without extending it somehow. Pandoc again lives up to its reputation as the swiss army knife of document conversion by supporting custom filtes. (In fact, if I were to approach this I'd try to build a generic bridge between docutils readers/transformers/writers and pandoc readers/filters/writers. It's more than you need but the payoff would be much wider than just sphinx/markdown.)

Alternative crazy idea: instead of extending markdown to handle Sphinx, extend reStructuredText to support (mostly) a superset of markdown! The beauty is you'll be able to use any Sphinx features as-is, yet be able to write most content in markdown.

既にかなりの構文重複があります。最も顕著なのは、リンク構文に互換性がないことです。マークダウンリンクと -style ヘッダーのサポートを RST に追加し、###デフォルト`backticks`の役割をリテラルに変更し、インデントされたブロックをリテラルを意味するように変更すると (RST は> ...現在引用符をサポートしています)、ほとんどのマークダウンをサポートする使用可能なものが得られると思います。 .

于 2010-03-21T16:53:55.687 に答える
34

これは Sphinx を使用しませんが、MkDocsは Markdown を使用してドキュメントを作成します。私も rst が嫌いで、今のところ MkDocs をとても楽しんでいます。

于 2014-04-07T17:36:12.863 に答える
33

2021 年 5 月の更新: recommonmark は廃止され、myst-parser が優先されます(thanks astrojuanlu)

更新:これは現在公式にサポートされており、sphinx docsに記載されています。

基本的な実装は Sphinx に組み込まれているようですが、まだ噂は広まっていません。githubの問題のコメントを参照してください

依存関係をインストールします。

pip install commonmark recommonmark

調整conf.py:

source_parsers = {
    '.md': 'recommonmark.parser.CommonMarkParser',
}
source_suffix = ['.rst', '.md']
于 2016-03-19T16:02:59.227 に答える
20

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

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

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

Sphinx プロジェクトから Markdown コンテンツの一部を参照し、RST を使用して全体的な情報アーキテクチャと大きなドキュメントの流れをスタブ化することは理にかなっているように思えます。マークダウンが行うことをマークダウンに任せます。これにより、ライターはテキストの作成に集中できます。

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

于 2013-06-21T05:31:54.253 に答える
8

このタスクに pandoc を使用するという Beni の提案に従いました。次のスクリプトをインストールすると、ソース ディレクトリ内のすべてのマークダウン ファイルが最初のファイルに変換されるため、すべてのドキュメントをマークダウンで記述できます。これが他の人に役立つことを願っています。

#!/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(' '))
于 2015-05-12T17:00:29.873 に答える
1

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

于 2013-05-07T23:45:30.603 に答える
0

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>
于 2017-12-05T14:29:06.020 に答える