Python项目的README扩展

Question

Python打包工具希望我们的自述文件应该命名为README或README.txt.但是,如果我们遵守这个约定,GitHub上显示为项目中的网页,其中不漂亮纯文本.(与名为README.rst的美丽HTML版本不同)

是否有任何技术可以使PyPI和GitHub对README感到高兴.

Answer 1

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 2

我能想到的一个粗略的方法是README调用一个符号链接README.rst并检查它们.

Answer 3

你可以使用git的过滤驱动程序,其会,在结账时,把你的README.md(由GitHub的需要),并产生一个适当的README(由Python的需要,虽然伦纳特Regebro的回答暗示的PyPI并没有要求任何README文件)

因此,撇开PyPI不需要README(并且可以简单地忽略警告)的事实,这里是你可以(通常)使用Git生成预期文件的方法:

但是,README需要手动向README.md文件报告对该私有文件的任何修改(至少因为没有脚本可以猜到的markdown语法)

这就是为什么Noufal Ibrahim的回答(我赞成的)可能更适应,特别是如果你有权访问符号链接(我在工作时仍然使用Windows Xp,所以对我来说没有运气):

具有使README作为一个符号链接到README.rst,或者,如阿尔托Bendiken注释:
=> 具有README.rst作为一个符号链接ROREADME.

Git将存储符号链接(而不是符号链接所引用的文件),因此您可以在Git仓库中同时拥有它们README和它的README.rst文件.

Answer 4

引用ÉricAraujo的Python bug关于distutils警告：

在Packaging / distutils2中，推荐的惯用法如下所示（在setup.cfg中）：

[metadata]
description-file = README.whatever

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

因此，从根本上讲，请忽略distutils有关缺失的警告README.txt。另外，distutils2据称不会发出此警告（我尚未测试），因此您可以尝试升级。