我有一个托管在GitHub上的项目。为此，我使用Markdown语法编写了自述文件，以便在GitHub上很好地格式化它。

由于我的项目使用Python，因此我还计划将其上传到PyPi。PyPi上用于README的语法为reStructuredText。

我希望避免处理两个包含大致相同内容的自述文件。因此，我搜索了RST（或相反）转换器的降价促销，但找不到任何商品。

我看到的另一个解决方案是执行markdown / HTML，然后执行HTML / RST转换。我在这里和这里都找到了一些资源，所以我猜应该是可行的。

您有什么想法可以更好地适合我的工作吗？

我会推荐Pandoc，“将文件从一种标记格式转换为另一种格式的瑞士军刀”（在页面底部查看受支持的转换图，这是非常令人印象深刻的）。Pandoc允许markdown直接进行reStructuredText翻译。此外，还有一个在线编辑器，在这里它可以让你尝试一下，所以你可以简单地使用在线编辑器来转换你的自述文件。

正如@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保留为两种格式。

您可以在文档中找到有关它的更多信息。

旧答案：

GitHub使用的标记库支持reStructuredText。这意味着您可以编写README.rst文件。

它们甚至使用code和code-block指令支持语法特定的颜色突出显示（示例）

PyPI现在支持Markdown进行详细描述！

在中setup.py，设置long_description为Markdown字符串，添加long_description_content_type="text/markdown"并确保您使用的是最新工具（setuptools38.6.0 +，twine1.11 +）。

有关更多详细信息，请参见Dustin Ingram的博客文章。

根据我的要求，我不想在计算机上安装Pandoc。我用了docverter。Docverter是具有HTTP接口的文档转换服务器，为此使用了Pandoc。

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

您可能还对以下事实感兴趣：可以编写一个公共子集，以便在以markdown呈现或以reStructuredText呈现时，文档以相同的方式出现：https: //gist.github.com/dupuy/1855764☺

我遇到了这个问题，并使用以下两个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文件。即使此解决方案意味着您同时拥有an md和an，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))