GitHubでホストされているプロジェクトがあります。このために、GitHubで適切にフォーマットするために、Markdown構文を使用してREADMEを作成しました。
私のプロジェクトはPythonであるため、PyPiにもアップロードする予定です。PyPiのREADMEに使用される構文はreStructuredTextです。
ほぼ同じコンテンツを含む2つのREADMEを処理する必要はありません。そこで、RST（またはその逆）トランスレータへのマークダウンを検索しましたが、見つかりませんでした。
私が見る他の解決策は、マークダウン/ HTMLを実行してから、HTML/RST変換を実行することです。私はこことここでこれのためのいくつかのリソースを見つけたので、それは可能であるはずだと思います。
私がやりたいことにもっと合うアイデアはありますか？
@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の混乱を気にする必要はありません。;）
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つの形式で保持する必要はありません。
詳細については、ドキュメントを参照してください。
GitHubで使用されるマークアップライブラリはreStructuredTextをサポートしています。これは、README.rstファイルを作成できることを意味します。
codeおよびcode-blockディレクティブを使用した構文固有の色の強調表示もサポートします（例）
PyPIは、長い説明のためにMarkdownをサポートするようになりました！
で、Markdown文字列にsetup.py設定し、追加して、最近のツール（38.6.0 +、1.11 +）を使用していることを確認します。long_descriptionlong_description_content_type="text/markdown"setuptoolstwine
詳細については、 DustinIngramのブログ投稿を参照してください。
また、共通のサブセットで記述して、マークダウンとしてレンダリングした場合やreStructuredTextとしてレンダリングした場合にドキュメントが同じように表示されるようにすることができるという事実にも興味があるかもしれません：https ： //gist.github.com/dupuy/1855764☺ </ p>
私の要件では、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
私はこの問題に遭遇し、次の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
お役に立てば幸いです
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))