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

Question

我正在开发具有以下布局的 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 和阅读文档上，链接应该重定向到阅读文档页面
在 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 如果 RST 也包含 include 指令，则不会呈现 RST。

Answer 1

如果您描述的第一次尝试足以满足 GitHub 和 RTD，那么问题就是如何为 PyPI 实现有效的长描述源，对吗？

在setup.py中，可以设置setup()关键字参数long_description_content_type='text/x-rst'，设置long_description为一串RST文本（no sphinx extensions），因此您可以在 setup.py.

之前使用任意 Python 代码预处理长描述源

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

How can I compose the content of my PyPI project description?

python

restructuredtext

github

pypi

read-the-docs