GitHubでホストされているプロジェクトがあります。このため、GitHubで適切にフォーマットするために、Markdown構文を使用してREADMEを作成しました。
私のプロジェクトはPythonにあるので、これも PyPi にアップロードする予定です。PyPiのREADMEに使用される構文はreStructuredTextです。
ほぼ同じコンテンツを含む2つのREADMEを処理する必要はありません。 RST(またはその逆)の翻訳者へのマークダウンを検索しましたが、見つかりませんでした。
私が見る他の解決策は、マークダウン/ HTMLを実行してからHTML/RST翻訳を実行することです。この here と here のリソースを見つけたので、可能だと思います。
私がやりたいことによりよく合うアイデアはありますか?
@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つの形式で保持する必要はありません。
詳細については documentation をご覧ください。
GitHubで使用される Markup ライブラリは、reStructuredTextをサポートします。これは、README.rstファイルを作成できることを意味します。
code
およびcode-block
ディレクティブを使用した構文固有の色の強調表示もサポートします( 例 )
PyPIは、長い説明のマークダウンをサポートするようになりました!
setup.py
、設定long_description
をMarkdown文字列に追加し、long_description_content_type="text/markdown"
そして、最新のツール(setuptools
38.6.0 +、twine
1.11+)を使用していることを確認してください。
詳細については、 Dustin Ingramのブログ投稿 を参照してください。
要件のために、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
また、共通のサブセットで記述して、ドキュメントをマークダウンとしてレンダリングする場合、またはreStructuredTextとしてレンダリングする場合に同じ方法で書き出すことができるという事実にも興味があるかもしれません。 https://Gist.github.com/ dupuy/1855764 ☺
この問題にぶつかり、次の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))