在Markdown和reStructuredText中都有相同的自述文件

Question

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

由于我的项目是Python,我还计划将其上传到PyPi.PyPi上用于README的语法是reStructuredText.

我想避免处理包含大致相同内容的两个README; 所以我搜索了RST(或其他方式)翻译的降价,但找不到任何.

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

你有什么想法可以更好地适应我想做的事情吗？

Answer 1

我会推荐Pandoc,"用于将文件从一种标记格式转换为另一种标记格式的瑞士军刀"(查看页面底部支持的转换图,非常令人印象深刻).Pandoc允许直接降格reStructuredText.此外,还有一个在线编辑器,在这里它可以让你尝试一下,所以你可以简单地使用在线编辑器来转换你的自述文件.

Answer 2

正如@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 - 当他们想要构建模块时不强制其他人安装pypandoc,而不是上传到PyPi.

所以你可以像往常一样写Markdown而不再关心RST的混乱.;)

Answer 3

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使用的Markup库支持reStructuredText.这意味着您可以编写README.rst文件.

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

Answer 4

您可能还对以下事实感兴趣：可以在公共子集中编写，以便您的文档在呈现为 markdown 或呈现为 reStructuredText 时以相同的方式显示：https: //gist.github.com/dupuy/1855764 \ xe2\x98\xba

\n

Answer 5

PyPI现在支持Markdown进行长描述!

在setup.py,设置long_description为Markdown字符串,添加long_description_content_type="text/markdown"并确保您使用的是最近的工具(setuptools38.6.0 +,twine1.11 +).

有关详细信息,请参阅Dustin Ingram的博客文章.