如何编写我的 PyPI 项目描述的内容？答案

【问题标题】：How can I compose the content of my PyPI project description?如何编写我的 PyPI 项目描述的内容？
【发布时间】：2020-03-10 05:33:00
【问题描述】：

我正在开发具有以下布局的Python project（使用 PyScaffold 设置）：

project/
 - src/
 - docs/
   - _static/
     - assets/
       - logo.svg
   - index.rst
 - README.rst
 - AUTHORS.txt
 - setup.py
 - setup.cfg
 - ...

此项目托管在 GitHub 上，发布在 Pypi 上，并记录在 ReadTheDocs 上。我希望这 3 个站点呈现与主页（自述文件、详细描述、索引页）相似的内容，但一些细节除外：

在 GitHub 上，链接应重定向到 GitHub 文件页面
在 Pypi 和 Read the Docs 上，链接应重定向到 Read the Docs 页面
在 GitHub 上的分支上，链接应该重定向到分支文件（不是 master 的）

目前，我使用的 README.rst 看起来像：

.. _Authors: http://readthedocs/latest/authors.html

.. |logo| image:: http://readthedocs/assets/logo.svg
   :alt: Logo
   :width: 500


.. EndOfLinks

|logo|

`Authors`_

如下docs/index.rst：

.. _Authors: ./authors.html

.. |logo| image:: ./_static/ewmh_m2m.svg
   :alt: Logo
   :width: 500

.. include:: ../README.rst
   :start-after: EndOfLinks

还有一个setup.cfg：

long-description = file: README.rst
long-description-content-type = text/x-rst; charset=UTF-8

但是，在新分支上，README 呈现或链接不会反映基础文件中的任何更改，例如 this example。

在 README 中使用相对链接会使 Pypi 描述中的链接断开，并且不会显示徽标（请参阅here）

我尝试使用专用的pypi_description.rst 文件，类似于index.rst Pypi 和GitHub 如果它也包含include 指令，则不呈现RST。

【问题讨论】：

这似乎至少是两个问题，但我可以看到很难弄清楚如何最好地划分它们。似乎您可能已经回答了“如何将我的 README.rst 的一部分写入 Sphinx 文档？”的问题。和“GitHub README.rst 可以从其他文件中插入内容吗？”。 “如何编写我的 PyPI 项目描述的内容？”的问题。可以通过packaging.python.org/guides/making-a-pypi-friendly-readme及其链接内容来回答。

标签： python github pypi restructuredtext read-the-docs

【解决方案1】：

如果你描述的第一次尝试对于 GitHub 和 RTD 来说已经足够了，那么问题就是如何为 PyPI 实现有效的长描述源，对吧？

在setup.py中，可以设置setup()关键字参数long_description_content_type='text/x-rst'并将long_description设置为一串RST文本（no sphinx extensions），这样就可以用任意Python代码预处理长描述源早在setup.py。

【讨论】：

这正是我在[您的评论]对我的问题之后所想的。目前，我使用限制功能的setup.cfg。在解析/复制README文件后，我将搜索如何使用setup.cfg和setup.py并从setup.py设置long_description。
我终于从 setup.cfg 文件中删除了 long_description 并在 setup.py 中预处理我的 README 以构建有效的长描述。见the code。谢谢。