Python项目的自述文件扩展

Question

Python打包工具希望我们的自述文件应该命名为readme或readme.txt。但是如果我们遵循这个约定，GitHub会在项目页面中将其显示为纯文本，这并不好看。（与名为README.rst的漂亮HTML版本不同）

有什么技术可以让PyPI和GitHub都对README感到满意吗。

Answer 1

我能想到的一个粗略的方法是创建一个名为README.rst的README的符号链接，并将它们都签入。

Answer 2

PyPI不要求文件名为README或README.txt，因此只需将其称为README.rst。事实上，就我所知，PyPI根本不会查看您的包（尽管我可能是错的，我没有研究过代码或其他东西），最后出现在前面的文本是long_description参数。

然后在setup.py中，执行以下操作：

setup(name='Your module name',
      version="1.0",
      description="Whatever, dude.",
      long_description=open('docs/README.rst', 'rt').read()
)

Answer 3

您可以使用一个git filter driver，在签出时，它将获取您的README.md（GitHub需要）并生成适当的README（Python需要，尽管Lennart Regebro的answer建议PyPI不需要任何README文件）

因此，撇开PyPI不需要自述文件这一事实不谈（警告可以被忽略），下面是如何（通常）使用Git生成预期的文件：

但是，对该私有文件README的任何修改都需要手动报告给README.md文件（至少因为没有脚本可以为您猜测的标记语法）

这就是为什么Noufal Ibrahim的answer（我投了更高的票）可能更适合，特别是如果您可以访问符号链接（我仍在使用Windows Xp，所以我运气不好）：

使README成为README.rst的符号链接，或者作为Arto Bendiken注释：
=>；将README.rst作为符号链接roREADME。

Git将存储符号链接（和not the file the symlink refers to），因此您可以在Git repo中同时拥有README及其README.rst文件。