web-dev-qa-db-ja.com

MarkdownとreStructuredTextの両方で同じREADMEを持つ

GitHubでホストされているプロジェクトがあります。このため、GitHubで適切にフォーマットするために、Markdown構文を使用してREADMEを作成しました。

私のプロジェクトはPythonにあるので、これも PyPi にアップロードする予定です。PyPiのREADMEに使用される構文はreStructuredTextです。

ほぼ同じコンテンツを含む2つのREADMEを処理する必要はありません。 RST（またはその逆）の翻訳者へのマークダウンを検索しましたが、見つかりませんでした。

私が見る他の解決策は、マークダウン/ HTMLを実行してからHTML/RST翻訳を実行することです。この here と here のリソースを見つけたので、可能だと思います。

私がやりたいことによりよく合うアイデアはありますか？

pythongithubmarkdownrestructuredtextpypi
114
jlengrand

Pandoc 、「あるマークアップ形式から別のマークアップ形式にファイルを変換するためのスイス軍のナイフ」をお勧めします（ページの下部にあるサポートされている変換の図をご覧ください。非常に印象的です）。 Pandocでは、マークダウンでreStructuredTextを直接翻訳できます。また、オンラインエディタ here を使用して試してみることができるため、オンラインエディタを使用してREADME=ファイルを変換できます。

88
Chris

@Chrisが示唆したように、Pandocを使用してMarkdownをRSTに変換できます。これはpypandocモジュールとsetup.pyの魔法を使用して簡単に自動化できます。

from setuptools import setup
try:
    from pypandoc import convert
    read_md = lambda f: convert(f, 'rst')
except ImportError:
    print("warning: pypandoc module not found, could not convert Markdown to RST")
    read_md = lambda f: open(f, 'r').read()

setup(
    # name, version, ...
    long_description=read_md('README.md'),
    install_requires=[]
)

これにより、PyPiでの長い説明のためにREADME.mdがRSTに自動的に変換されます。 pypandocが利用できない場合は、変換せずにREADME.mdを読み取ります。PyPiにアップロードするのではなく、モジュールをビルドするだけのときにpypandocを強制的にインストールしないようにします。

そのため、通常どおりMarkdownで記述でき、RSTの混乱はもう気にしません。 ;）

47
Jakub Jirutka

2019アップデート

PyPI Warehouse 現在サポート Markdownもレンダリング！パッケージ構成を更新し、long_description_content_type='text/markdown'を追加するだけです。例えば。：

setup(
    name='an_example_package',
    # other arguments omitted
    long_description=long_description,
    long_description_content_type='text/markdown'
)

したがって、README=を2つの形式で保持する必要はありません。

詳細については documentation をご覧ください。

古い答え：

GitHubで使用される Markup ライブラリは、reStructuredTextをサポートします。これは、README.rstファイルを作成できることを意味します。

codeおよびcode-blockディレクティブを使用した構文固有の色の強調表示もサポートします（ 例 ）

28
Cesar Canassa

PyPIは、長い説明のマークダウンをサポートするようになりました！

setup.py、設定long_descriptionをMarkdown文字列に追加し、long_description_content_type="text/markdown"そして、最新のツール（setuptools 38.6.0 +、twine 1.11+）を使用していることを確認してください。

詳細については、 Dustin Ingramのブログ投稿 を参照してください。

5
Petr Viktorin

要件のために、Pandocをコンピューターにインストールしたくありませんでした。 docverterを使用しました。 Docverter は、このためにPandocを使用するHTTPインターフェイスを備えたドキュメント変換サーバーです。

import requests
r = requests.post(url='http://c.docverter.com/convert',
                  data={'to':'rst','from':'markdown'},
                  files={'input_files[]':open('README.md','rb')})
if r.ok:
    print r.content
4
David Miró

また、共通のサブセットで記述して、ドキュメントをマークダウンとしてレンダリングする場合、またはreStructuredTextとしてレンダリングする場合に同じ方法で書き出すことができるという事実にも興味があるかもしれません。 https://Gist.github.com/ dupuy/1855764 ☺

3
Zooko

この問題にぶつかり、次の2つのbashスクリプトで解決しました。

LaTeXがMarkdownにバンドルされていることに注意してください。

#!/usr/bin/env bash

if [ $# -lt 1 ]; then
  echo "$0 file.md"
  exit;
fi

filename=$(basename "$1")
extension="${filename##*.}"
filename="${filename%.*}"

if [ "$extension" = "md" ]; then
  rst=".rst"
  pandoc $1 -o $filename$rst
fi

Htmlへの変換にも便利です。 md2html：

#!/usr/bin/env bash

if [ $# -lt 1 ]; then
  echo "$0 file.md <style.css>"
  exit;
fi

filename=$(basename "$1")
extension="${filename##*.}"
filename="${filename%.*}"

if [ "$extension" = "md" ]; then
  html=".html"
  if [ -z $2 ]; then
    # if no css
    pandoc -s -S --mathjax --highlight-style pygments $1 -o $filename$html
  else
    pandoc -s -S --mathjax --highlight-style pygments -c $2 $1 -o $filename$html
  fi
fi

それがお役に立てば幸いです

1
Chet

他の人が提案したpandocツールを使用して、md2rstユーティリティは、rstファイルを作成します。この解決策はmdとrstの両方を持っていることを意味しますが、最も侵襲性が低く、将来のマークダウンサポートが追加された場合でもそれを可能にします。私はsetup.pyそしておそらくあなたもそうするでしょう：

#!/usr/bin/env python

'''
Recursively and destructively creates a .rst file for all Markdown
files in the target directory and below.

Created to deal with PyPa without changing anything in setup based on
the idea that getting proper Markdown support later is worth waiting
for rather than forcing a pandoc dependency in sample packages and such.

Vote for
(https://bitbucket.org/pypa/pypi/issue/148/support-markdown-for-readmes)

'''

import sys, os, re

markdown_sufs = ('.md','.markdown','.mkd')
markdown_regx = '\.(md|markdown|mkd)$'

target = '.'
if len(sys.argv) >= 2: target = sys.argv[1]

md_files = []
for root, dirnames, filenames in os.walk(target):
    for name in filenames:
        if name.endswith(markdown_sufs):
            md_files.append(os.path.join(root, name))

for md in md_files:
    bare = re.sub(markdown_regx,'',md)
    cmd='pandoc --from=markdown --to=rst "{}" -o "{}.rst"'
    print(cmd.format(md,bare))
    os.system(cmd.format(md,bare))
0
robmuh