python / python/cpython

Link from typing docs to specific sections in the typing spec

Offen
#117,539 4 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen

Dieses Issue hat noch niemand übernommen.

docs topic-typing
Vorherrschende Sprache
Python
Sterne
77.2k
Forks
36k
PR-Merge-Kennzahlen
PR-Kennzahlen ausstehend

Beschreibung

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

Beitragsleitfaden

Beitragsleitfaden öffnen

Erste Schritte

  1. Lies das ganze Issue und danach den Beitragsleitfaden des Projekts.
  2. Schreib ins Issue, dass du es übernimmst — das erspart doppelte Arbeit.
  3. Forke das Repository und arbeite in einem Branch.
  4. Öffne einen Pull Request, der die Issue-Nummer nennt.

Rechercherichtung

Beginne mit der Überprüfung der Links zur typing-Dokumentation und der intersphinx-Konfiguration. Untersuche anschließend den Protocol-Docstring in Lib/typing.py rund um den referenzierten PEP-544-Link. Entscheide, wie sowohl die Online-Dokumentation als auch Docstrings auf die aktuelle typing-Spezifikation verweisen sollten, und überprüfe, dass die relevanten Links die vorgesehenen Abschnitte der Spezifikation verwenden.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Bewertung

Tech-Stack
python
Bereich
documentation
Issue-Typ
Dokumentation
Schwierigkeit
3/5
Geschätzter Aufwand
1-2 Tage
Aktivitätsstatus
Veraltet
Klarheit
Größtenteils klar
Anfängerfreundlichkeit
35/100

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.