Python 项目的 README 扩展

Question

Python的打包工具希望我们的说明文件叫做README或者README.txt。但是如果我们按照这个规则来命名，GitHub会把它当成普通文本显示在项目页面上，看起来就不太好看。（而如果命名为README.rst，GitHub会显示得很漂亮，像网页一样）

有没有什么办法可以让PyPI和GitHub都满意我们的README文件呢？

Answer 1

我想到一个简单的方法，就是创建一个指向README的符号链接，叫做README.rst，然后把这两个文件都提交上去。

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 过滤驱动 的工具，它可以在你检出代码时，把你的 README.md（GitHub需要的文件）转换成一个合适的 README 文件（Python需要的文件，虽然 Lennart Regebro 的 回答 提到PyPI其实并不需要任何README文件）

所以，抛开PyPI不需要README这个事实（你可以选择忽略这个警告），下面是你可以（一般来说）用Git生成所需文件的方法：

不过，任何对那个私有文件 README 的修改都需要手动更新到 README.md 文件中（至少因为markdown语法是脚本无法自动处理的）

这就是为什么 Noufal Ibrahim 的 回答 可能更适合你的原因，特别是如果你可以使用符号链接的话（我在工作中还是用Windows XP，所以对我来说没戏）：

可以让 README 指向 README.rst，或者正如 Arto Bendiken 评论的那样：
=> 让 README.rst 指向 README。

Git会存储这个符号链接（而不是符号链接指向的文件），所以你可以在你的Git仓库中同时拥有 README 和 README.rst 文件。