Python 项目的 README 扩展答案

【问题标题】：README extension for Python projectsPython 项目的 README 扩展
【发布时间】：2011-05-22 01:14:27
【问题描述】：

Python 打包工具要求我们的自述文件应命名为 README 或 README.txt。但是如果我们遵循这个约定，GitHub 会在项目页面中将其显示为纯文本，这并不美观。（不同于命名为 README.rst 的漂亮的 HTML 版本）

有什么技术可以让 PyPI 和 GitHub 都对 README 感到满意。

【问题讨论】：

PyPI 不期望文件被命名为 README 或 README.txt。我不知道你指的是什么 Python 打包工具，但我不知道有什么需要这种命名的，如果需要的话，很可能很容易修复。
Lennart，当我在没有 README 的情况下运行 setup.py sdist 时，它会显示 warning: sdist: standard file not found: should have one of README, README.txt... 但我想这只是我可以忽略的抱怨？
@rescdsk：是的，你可以忽略它。 AFAIK 没有任何东西可以使用它。事实上，这确实应该作为错误报告提交。
bugs.python.org/issue11913
如果您希望 PyPI 支持 Markdown 中的自述文件，请在 bitbucket.org/pypa/pypi/issue/148/support-markdown-for-readmes 对功能请求发表评论

【解决方案1】：

PyPI 不要求文件名为 README 或 README.txt，因此只需将其命名为 README.rst。事实上，据我所知，PyPI 根本不会查看你的包（虽然我可能错了，我没有研究过代码或任何东西），前面的文本是 @987654321 @参数。

然后在你的 setup.py 中，你做这样的事情：

setup(name='Your module name',
      version="1.0",
      description="Whatever, dude.",
      long_description=open('docs/README.rst', 'rt').read()
)

【讨论】：

伦纳特是对的。 PyPI 可以解析 long_description 中的 reST，它不使用 README。警告只是警告；将您的文件命名为 README 或忽略警告。 Packaging/distutils2 更智能；有关更多信息，请参阅错误报告。

【解决方案2】：

我能想到的一种粗略的方法是创建一个指向 README 的符号链接，名为 README.rst 并将它们都签入。

【讨论】：

这就是我所做的，尽管反过来：README 是指向README.rst（或README.md，对于非 Python 项目）的符号链接。
+1，好点，虽然@Arto 的方式也很有意义。我已将其包含在我的答案中，并附有链接并为您的答案点赞。
是的，我在 github 上使用了 README.md。

【解决方案3】：

您可以使用git filter driver，它会在结帐时获取您的README.md（GitHub 需要）并生成正确的README（Python 需要，尽管Lennart Regebro 的answer 建议PyPI 不需要需要任何 README 文件）

所以，抛开 PyPI 不需要 README 的事实（警告可以简单地忽略），以下是您可以（通常）使用 Git 生成预期文件的方法：

但是，对该私有文件 README 的任何修改都需要手动报告给 README.md 文件（至少因为没有脚本可以为您猜测的 markdown 语法）

这就是为什么Noufal Ibrahim 的answer（我赞成）可能更适合，特别是如果您可以访问符号链接（我仍在使用 Windows Xp 工作，所以我运气不好）：

使README 成为README.rst 的符号链接，或者作为Arto Bendiken cmets：
=> 拥有README.rst 是一个符号链接ro README。

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

【讨论】：

【解决方案4】：

在Python bug about the distutils warning 引用 Éric Araujo：

在 Packaging/distutils2 中，推荐的成语如下所示（在 setup.cfg 中）：
[metadata]
description-file = README.whatever
sdist 将包含该文件。您也可以直接在 setup.cfg 中编写描述，并将您的 README 文件包含在 extra_files 字段中。

所以，基本上，忽略来自distutils 的关于缺少README.txt 的警告。另外，distutils2 应该不会发出这个警告（我没有测试过），所以你可以尝试升级。

【讨论】：

【解决方案5】：

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

【讨论】：