python / python/docs-community

Preserve documentation deep links across layout changes

オープン
#134 コメント 3 件 リアクション 0 件 担当者 1 名 GitHub で見る

@StanFromIreland がすでに取り組んでいます。

2026年6月8日 から。

主要言語
Makefile
スター
55
フォーク
26
PR マージ指標
30日以内にマージされた PR はありません

説明

(Tooling request extracted from https://github.com/python/cpython/issues/126053 and https://github.com/python/cpython/issues/126052)

One of the barriers to making significant structural changes to the CPython docs is that we're likely to break deep links by doing so. For example, if https://docs.python.org/3/library/stdtypes.html were to be split up into per-category or per-type pages, any links to specific sections like String methods would just break (giving either 404 or linking to the top of the page instead of the desired information). We don't want to do that.

At the same time, not being able to refactor these pages poses significant problems for documentation readability (in the two linked examples, one of the pages contains 18+ thousand words, and the other is 25k+).

In https://github.com/python/cpython/issues/126053#issuecomment-2441975654, we identified a potential technical mitigation that would allow moving link targets between pages, or making other changes (like updating section headings), without necessarily breaking deep links to those anchors:

  • define a way to essentially do an "anchor diff" between two versions of a set of docs to find anchors and pages which used to exist but will no longer resolve (for example, define https://docs.python.org/dev/ as the reference docs for main, and compare each new build to those. It might be sufficient to use the existing intersphinx inventory as the basis for comparison).
  • define a way to map removed anchors on affected pages to new targets (targets should be Sphinx semantic references). This may be a new Sphinx extension with a custom directive like .. anchormap::, or it may be something else.
  • when a page has an anchor map defined, inject the client side JS to intercept stale links and generate the relevant JS redirect request (if the page has no anchor map, there's no need to inject that JS snippet).
  • add a docs CI check that fails if anchors are removed relative to the baseline docs without an anchor map entry being defined

We may also want to provide guidance on implementing full page redirects (along the lines of https://github.com/pypa/packaging.python.org/blob/main/source/guides/single-sourcing-package-version.rst?plain=1), as the tooling would need to be aware of those to avoid having them show up as broken deep links.

コントリビューションガイド

このリポジトリのコントリビューションガイドは索引されていません

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

評価

この issue はまだ評価されていません。

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。