python / python/cpython

Link from typing docs to specific sections in the typing spec

未关闭
#117,539 4 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看

还没有人认领这个 Issue。

docs topic-typing
主要语言
Python
星标
77.2k
派生
36k
PR 合并指标
PR 指标待抓取

描述

The typing docs currently frequently link to the PEPs that defined new typing features. Instead, they should link to the typing spec, which unlike the PEPs is a living document.

In the online documentation, we can do this with intersphinx. I have this running locally and can send a PR.

I'm less sure about how to handle this in the docstrings. For example, Protocol's docstring refers to PEP 544: https://github.com/python/cpython/blob/b32789ccb91bbe43e88193f68b1364a8da6d9866/Lib/typing.py#L1987. Should we provide a full URL to the spec, like https://typing.readthedocs.io/en/latest/spec/protocol.html?

Linked PRs
  • gh-117540

贡献指南

打开贡献指南

从这里开始

  1. 先读完整个 Issue,再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库,在一个分支上完成修改。
  4. 提交 Pull Request,并在描述里引用这个 Issue 编号。

调研方向

首先检查 typing 文档链接和 intersphinx 配置,然后查看 Lib/typing.py 中所引用的 PEP 544 链接附近的 Protocol 文档字符串。确定在线文档和文档字符串应如何指向现行的 typing 规范,并验证相关链接使用了规范中预期的章节。

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

评估

技术栈
python
领域
documentation
Issue 类型
文档
难度
3/5
预计耗时
1-2 天
活跃度
停滞
描述清晰度
基本清楚
新手友好度
35/100

把新 issue 发到你的邮箱

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