python / python/docs-community

Preserve documentation deep links across layout changes

Đang mở
#134 3 bình luận 0 reaction 1 người được giao Xem trên GitHub

@StanFromIreland đang làm issue này rồi.

Từ ngày 8/6/2026.

Ngôn ngữ chính
Makefile
Star
55
Fork
26
Chỉ số merge pull request
Không có pull request nào được merge trong 30 ngày

Mô tả

(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.

Hướng dẫn đóng góp

Chưa lập chỉ mục được hướng dẫn đóng góp cho kho mã nguồn này

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Đánh giá

Issue này chưa được đánh giá.

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.