markdown - Sphinxベースのドキュメントのマークダウン出力

Question

SphinxベースのドキュメントソースからHTMLとPDFを生成することに加えて、 reStructuredTextソースファイルのMarkdownバージョンも生成したいというユースケースに気づきました。

私の予備調査では、 Sphinxでこれに対するコアまたは拡張機能のサポートは見つかりませんでした。pandocを手動で使用するか、タスクの新しいSphinx拡張機能を作成する以外に、これに対するより単純でより統合されたソリューションはありますか？

Answer 1

Pandocを除いて、reStructuredTextファイルを取得してMarkdownに変換できるものが見つからなかったため、Docutilsのカスタムライター（reStructuredTextのリファレンス実装とSphinxの基盤）を作成しました。コードはGitHubで入手できます。

これは初期実装にすぎないことに注意してください。エラーなしでreStructuredTextドキュメントを処理します（ Docutilsソースリポジトリからのstandard.txtテストドキュメントに対してテストされます）が、reStructuredTextコンストラクトの多く（置換、rawディレクティブなど）はサポートされておらず、したがって、Markdown出力には含まれません。リンク、コードブロック、画像、表のサポートを追加したいと思っています。これに向けたサポートは大歓迎です。コードをフォークしてください。

Sphinxに別のライター/出力フォーマットを追加するには、拡張子を使用して「ビルダー」を追加する必要があるようです。

Answer 2

2018年11月の更新：sphinx-markdown-builderが利用可能になりました-@Jam Risserのおかげで：

インストール

pip3 install sphinx-markdown-builder

依存関係

Python 3

使用法

構成に拡張機能をロードします。

conf.py

extensions = [
    'sphinx_markdown_builder'
]

recommonmarkを使用する場合は、システムと競合するため、ビルドファイルを明示的に無視するようにしてください。

conf.py

exclude_patterns = [
    'build/*'
]

Makefileを使用してマークダウンファイルを作成する

make markdown

sphinx-buildコマンドを使用してマークダウンファイルをビルドする

cd docs
sphinx-build -M markdown ./ build

参考文献

• https://github.com/codejamninja/sphinx-markdown-builder/
• https://pypi.org/project/sphinx-markdown-builder/

ps。古い元の回答（sphinx-markdown-builder現在利用可能になっているため）：Sphinxプロジェクトサイトで直接Markdown出力サポートの機能リクエストを作成しました： https ： //github.com/sphinx-doc/sphinx/issues/4219そのgithubリクエストに賛成したすべての人に感謝します-それは違い！

Answer 3

pandocを使用したい場合は、sphinx-quickstart.pyを初めて実行してreStructuredTextをMarkdownに変換するときに、Sphinxが生成するMakefileを単純に変更しないのはなぜですか？
これが最も簡単なソリューションですが、Makefileに組み込むと、Chrisのソリューションも機能するはずです。