Python项目的README扩展

Question

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

是否有任何技术可以让PyPI和GitHub对README感到满意。

Answer 1

PyPI不要求文件名为README或README.txt，因此只需将其称为README.rst。实际上，根据我的意识，PyPI根本不会在你的包中看到（尽管我可能在那里错了，我还没有研究过代码或其他任何内容），最前面的文本是{{{ 1}}参数。

然后在你的setup.py中，你做了类似的事情：

long_description

Answer 2

我能想到的一种粗俗方法是对名为README的{​​{1}}制作一个符号链接，然后检查它们。

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注释：
=＆GT; 让README.rst成为符号链接ro README 。

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

Answer 4

在Python bug about the distutils warning：

引用ÉricAraujo

  

在packaging / distutils2中，推荐的习语看起来像这样（在setup.cfg中）：

[metadata]
description-file = README.whatever

     

sdist将包含该文件。您也可以直接在setup.cfg中编写描述，并将自述文件包含在extra_files字段中。

所以，基本上，忽略distutils关于遗失README.txt的警告。此外，distutils2据说不会发出此警告（我尚未测试过），因此您可以尝试升级。

Answer 5

在旧的（非distutils2）设置中，您可以明确地将README.rst添加到MANIFEST.in文件中。您仍然会看到关于标准README {.txt}缺席的警告，但您的README.rst将包含在您的sdist tarball中，这意味着它将包含在直接从PIPY下载的最终用户中。

有关详细信息，请参阅http://docs.python.org/2/distutils/sourcedist.html#the-manifest-in-template。