bazel-contrib / bazel-contrib/rules_python

`py_wheel`: Summary, Description, Description-Content-Type

未关闭
#841 2 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看
Good first issue type: documentation
主要语言
Starlark
星标
688
派生
721
平均合并
15 小时 7 分钟
30 天内合并 PR
76

描述

# 🚀 feature request and documentation 🐞 bug report

### Relevant Rules

`py_wheel`

### Description

The documentation of the `description_file` attribute of `py_wheel` describes the attribute as "A file containing text describing the package in a single line."

This directly contradicts the core metadata specifications, https://packaging.python.org/en/latest/specifications/core-metadata/#description, which states

> A longer description of the distribution that can run to several paragraphs. Software that deals with metadata should not assume any maximum size for this field, though people shouldn’t include their instruction manual as the description.

There is, however, another field in the core metadata specifications that actually matches the description, https://packaging.python.org/en/latest/specifications/core-metadata/#summary:

> Summary
> A one-line summary of what the distribution does.

I'm not entirely sure if this should be a bug report or a feature request, because both "Description" and "Summary" would be nice to have. I'm assuming that compliance with the [PyPA specifications](https://packaging.python.org/en/latest/specifications/) is intended, in which case it is at least a documentation bug. The `description_file` attribute ends up as the "Description", and can be several paragraphs. But it would be nice to also support the "Summary" field using a different attribute, and it would also be nice to be able to set the "Description-Content-Type field, https://packaging.python.org/en/latest/specifications/core-metadata/#description-content-type, so at least in those parts it's a feature request as well.

### Describe the solution you'd like

1. Documentation of `description_file` updated to support more than one line of description.
2. New attribute `summary` for the one-line description, setting [Summary](https://packaging.python.org/en/latest/specifications/core-metadata/#summary)
3. New attribute `description_content_type` for specifying markup syntax, setting [Description-Content-Type](https://packaging.python.org/en/latest/specifications/core-metadata/#description-content-type)

贡献指南

打开贡献指南

调研方向

从 `py_wheel` 规则开始,追踪 `description_file` 的文档说明以及它如何映射到 Python 核心元数据中。将该行为与链接的 Summary、Description 和 Description-Content-Type 规范进行比较,然后验证文档和所请求的三个元数据属性是否如描述的那样工作。

由索引模型根据 Issue 内容生成。

评估

技术栈
python
领域
build-system
Issue 类型
功能
难度
3/5
预计耗时
1-2 天
活跃度
活跃
描述清晰度
基本清楚
新手友好度
68/100

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。