Docs need support for a multiversion changed/added marker.

未关闭

#101,716 创建于 2023年2月8日 1 条评论 1 个 reaction 已指派 0 人在 GitHub 查看

还没有人认领这个 Issue。

评估

难度: 5/5
预计耗时: 一周以上
新手友好度: 35/100

Issue 类型: 功能
描述清晰度: 基本清楚
活跃度: 停滞
技术栈: python
领域: documentation

调研方向

首先检查现有的 ReST versionchanged 和 versionadded 指令，以及它们如何渲染版本值。定义多版本的语法和渲染行为，包括已回移植的安全修复以及过滤未来版本；完成的标准是文档能够显示每个适用的 release，且无需手动消除歧义。

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

描述

docs type-feature

Documentation

We have .. versionchanged:: NUMERIC TEXT and .. versionadded:: NUMERIC TEXT support in our ReST docs.

But I believe it must be a single numeric value/word to render meaningfully? What we lack is the less commonly needed ability to specify multiple versions at once. Typically for a subset of security fix backports.

Today's common practice has been to just list the relevant version from the branch being committed to (example: in main 3.12 today, in 3.11: 3.11.99, etc.) with a manual change to the docs required within each backport PR.

This is somewhat unsatisfactory for documentation readers: People often link to and read the latest /3/ docs on the website regardless of the Python version they are using. Where a version marker saying something happened in a specific release often ignores that the change was back-ported to older releases. Meaning people may not realize that unless they happen to bother loading the older version specific documentation.

note: Adding multi-version support in the tags wouldn't address the manual PR change on back-port issue (references to future versions in changed/added markers don't belong there... unless we could we auto-filter those out based on version number at doc compilation time?) - but that, or better, automating initial version population into those fields from the surrounding codebase, belongs in a separate feature request.

主要语言: Python
星标: 77.2k
派生: 36k
平均合并: 1 天 9 小时
30 天内合并 PR: 558