Python项目的README可能存在的冲突

Python打包工具要求README文件命名为README或README.txt。遵循此约定后，GitHub会以纯文本形式显示在项目页面中，不好看。（不像命名为README.rst时那样有漂亮的HTML版本）。有没有什么办法同时让PyPI和GitHub对README感到满意?

2、解决方案

方法一：PyPI中不需要READMETXT

PyPI没有要求将文件命名为README或README.txt，所以直接命名为README.rst即可。事实上，据我所知，PyPI根本不会查看你的包（尽管我可能错了，我没有研究过代码或其他东西），最终出现在前端的文本是long_description参数。
接下来，在setup.py中，做类似这样的事情：

setup(name='Your module name',
      version="1.0",
      http://www.jshk.com.cn/mb/reg.asp?kefu=xiaoding；//爬虫IP免费获取；
      description="Whatever, dude.",
      long_description=open('docs/README.rst', 'rt').read()
)

方法二：在Git中创建软链接

我想到一个简单的办法，就是在README上创建一个指向README.rst的软链接，然后一起签入。

方法三：使用Git过滤器驱动

你可以使用一个git过滤器驱动，它将在检出时采用你的README.md（GitHub需要），并生成一个合适的README（Python需要，尽管Lennart Regebro的答案表明PyPI不需要任何README文件）。所以，撇开PyPI不需要README的事实（并且可以简单地忽略警告），下面是如何使用Git生成期望的文件：

git config filter.READMEgenerate.clean  "rm -f README"
git config filter.READMEgenerate.smudge "ln -s README.rst README"
git config alias.checkreadme "log --grep=README.rst"

但是，对该私有文件README的任何修改都需要手动报告给README.md文件（至少是因为markdown语法，没有任何脚本可以猜测），这就是为什么Noufal Ibrahim的答案（我投了赞成票）可能更适合，特别是如果你可以使用符号链接（我还在工作中使用Windows Xp，所以我不走运）：

使README成为指向README.rst的符号链接，或者，正如Arto Bendiken评论的：
=> 让README.rst成为README的符号链接。Git将存储符号链接（而不是符号链接所引用的文件），因此你可以在Git repo中同时拥有README及其README.rst文件。

方法四：使用setup.cfg进行配置

在Python错误中的Éric Araujo引用了关于distutils警告的内容：

在packaging/distutils2中，推荐的惯用语如下（在setup.cfg中）：

[metadata]
description-file = README.whatever

sdist将包括该文件。你也可以直接在setup.cfg中编写描述，并使用extra_files字段包含你的README文件。所以，基本上，忽略distutils关于缺少README.txt的警告。此外，据说distutils2不会发出此警告（我没有测试过），所以你可以尝试升级。

方法五：在MANIFEST.in文件中手动添加README

在旧的（非distutils2）设置中，你可以将README.rst显式添加到MANIFEST.in文件中。你仍然会看到一条警告，指出缺少标准的README{.txt}，但你的README.rst将包含在sdist tar包中，这意味着它将包含在直接从PIPY下载的最终用户中。有关更多详细信息，请参见http://docs.python.org/2/distutils/sourcedist.html#the-manifest-in-template。