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

私のプロジェクトはPythonであるので、それをPyPiにアップロードすることも計画しています。PyPiのREADMEで使用される構文はreStructuredTextです。

ほぼ同じ内容を含む2つのREADMEを処理する必要がないようにしたいと思います。そのため、RST（またはその逆）トランスレータへのマークダウンを検索しましたが、見つかりませんでした。

もう1つの解決策は、マークダウン/ HTMLを実行してから、HTML / RST変換を実行することです。こことここでいくつかのリソースを見つけたので、それは可能だと思います。

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

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

@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の混乱を気にする必要はありません。;）

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つの形式で保持する必要はありません。

詳細については、ドキュメントをご覧ください。

古い答え：

マークアップはGitHubで使用されるライブラリはreStructuredTextのをサポートしています。つまり、README.rstファイルを作成できます。

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

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

で、Markdown文字列setup.pyに設定long_descriptionし、追加してlong_description_content_type="text/markdown"、最新のツール（setuptools38.6.0以降、twine1.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スクリプトで解決しました。

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

#!/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))