小开

最佳答案

我建议使用潘多克，这是一种“将文件从一种标记格式转换为另一种标记格式的瑞士军刀”(查看页面底部的支持转换图，非常令人印象深刻)。潘多克允许 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=[]
)

这将自动将 README.md 转换为 RST，以获得在 PyPi 上使用的长描述。当 Pypandoc不可用时，它只读取 README.md 而不进行转换——以避免其他人只想构建模块而不想上传到 PyPi 时强制安装 pypandoc。

这样你就可以像往常一样写入 Markdown，不用再关心 RST 的混乱了。 ;)

小开

2019年最新情况

PyPI 仓库现在支持也呈现 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指令(例子)进行语法特定的颜色突出显示

小开

使用别人建议的 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))

小开

我遇到了这个问题，并用以下两个 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

希望能帮上忙

小开

你可能还会感兴趣的一个事实是，它可以写在一个共同的子集，这样你的文档出来时，呈现为标记或呈现为 ReStructuredText:

小开

出于我的需要，我不想在我的电脑上安装 Pandoc。我用了博士。医生是一个文档转换服务器，其 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

小开

PyPI 现在支持长描述的 Markdown！

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

有关详细信息，请参阅达斯汀 · 英格拉姆的博客文章。

使用相同的自述 ReStructuredText

2019年最新情况

老答案: