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。