docs(sphinx): redirect the pdoc-era URLs and fix the stub's anchor rewriting

The site publishes into one mutable directory: each release's build replaces
sdk-docs/python/ wholesale, so a retired layout's pages are deleted rather
than kept. sdk-docs' own history is therefore the record of every URL the site
has served. Across 63 Python builds it has served 342; 145 resolve today.

197 are dead. 14 are viewcode listings, which redirects cannot cover because
they are not Sphinx documents. The other 183 are content pages, and 180 of
them come from the pdoc generation (v3.0-v7.0), which named a page after each
module path. Two commits did most of the damage, both by adding __all__ to a
package __init__: pdoc filters submodules through it, so v5.4.0 deleted the
nine pinecone/grpc/* pages and v7.0.0 took the tree from 84 pages to 2. v4
never published docs at all -- the workflow had no caller then -- so its URLs
are v3.2.2's, and rebuilding v4.0.0 confirms an identical page set.

Targets are not guesses. A page goes to the page its documented symbol lives
on today, checked against an index of every anchor in the current build;
failing that, to the page for a subject the docs still cover; failing that, to
index.html, which is honest about there being no counterpart rather than
stranding the reader somewhere plausible-looking. 97 of the 183 land there.

The stub template needed three fixes for any of this to work:

Its anchor remap was gated on the target starting with the literal "reference/",
which is only true for a stub at the docs root. Every entry added here is
nested, so the remap would have silently done nothing for all of them. The
stub now reads the "../" prefix off its own target and reuses it.

The remap mapped renamed classes, but 10.0's change was moving control-plane
verbs onto sub-resources, which renames the member too. rest.html's
where it does not exist; it is Indexes.create now. One member map covers the
sync, asyncio and gRPC clients, which split identically.

grpc.html#pineconegrpc forwarded into reference/grpc.html, which stopped
documenting PineconeGRPC when it merged into Pinecone -- a redirect landing on
a page about something else. That and 20 further section anchors, verified
present in the v8 build and mapped to ids verified present in this one, are
now in the sections table.

check_redirect_anchors.py guards the tables: every page they name must exist,
every fragment must be an id on the page it is paired with. This failure mode
is invisible otherwise, since the browser loads the page and just does not
scroll. It validates the entries present; it cannot know an anchor is missing
one it ought to have.

published-urls.txt grows by the 183 new stubs via --update, per #655.

Author: jhamon

.github/workflows/on-push.yml

@@ -342,3 +342,9 @@ jobs:
       # and deterministic; docs/published-urls.txt is the committed inventory.
       - name: Check published docs URLs still resolve
         run: uv run --no-sync python scripts/check_docs_urls.py
+
+      # A stub that rewrites a fragment to somewhere that no longer exists
+      # fails silently: the page loads and simply does not scroll. Nothing
+      # else in the build notices.
+      - name: Check redirect anchor targets still exist
+        run: uv run --no-sync python scripts/check_redirect_anchors.py

docs/_templates/redirect.html

@@ -9,6 +9,12 @@
 (function () {
   var target = "${to_uri}";
   var hash = window.location.hash;
+  // A stub sits at whatever depth its old URL had, so its target carries a
+  // matching "../" prefix. Any page substituted below has to carry the same
+  // one. Stubs that forward somewhere other than reference/ never rewrite a
+  // fragment, because only the reference pages carry autodoc anchors.
+  var into = target.match(/^((?:\.\.\/)*)reference\//);
+  var prefix = into ? into[1] : "";
   // Classes that were renamed or moved to a different page in 10.0. Each row is
   // the old autodoc id, the reference/ page the class now lives on, and its new
   // id. A hash is either the class id itself or that id followed by ".<member>",
@@ -27,29 +33,108 @@
     ["pinecone.admin.resources.OrganizationResource", "admin.html", "pinecone.admin.organizations.Organizations"],
     ["pinecone.admin.resources.ProjectResource", "admin.html", "pinecone.admin.projects.Projects"]
   ];
-  // Section anchors the old landing page linked to, which now map to a whole page.
+  // 10.0 moved the control-plane verbs off the client classes onto sub-resource
+  // objects, so a rename of the owning class is not enough to place them: the
+  // member name changed too. The split is identical for the sync, asyncio and
+  // gRPC clients, so one map serves all three and only the module and the class
+  // prefix differ. Verbs absent here stayed on the client and need no rewrite.
+  var verbs = {
+    "create_index": ["indexes", "create"],
+    "delete_index": ["indexes", "delete"],
+    "describe_index": ["indexes", "describe"],
+    "list_indexes": ["indexes", "list"],
+    "configure_index": ["indexes", "configure"],
+    "has_index": ["indexes", "exists"],
+    "create_index_for_model": ["indexes", "create_for_model"],
+    "create_backup": ["indexes", "create_backup"],
+    "describe_backup": ["indexes", "describe_backup"],
+    "list_backups": ["indexes", "list_backups"],
+    "delete_backup": ["backups", "delete"],
+    "create_collection": ["collections", "create"],
+    "delete_collection": ["collections", "delete"],
+    "describe_collection": ["collections", "describe"],
+    "list_collections": ["collections", "list"],
+    "describe_restore_job": ["restore_jobs", "describe"],
+    "list_restore_jobs": ["restore_jobs", "list"]
+  };
+  var resources = {
+    "indexes": "Indexes",
+    "collections": "Collections",
+    "backups": "Backups",
+    "restore_jobs": "RestoreJobs"
+  };
+  // Old client class, the page it now lives on, its module, and the prefix its
+  // sub-resource class names take.
+  var clients = [
+    ["pinecone.Pinecone", "pinecone.html", "pinecone.client", ""],
+    ["pinecone.PineconeAsyncio", "async-pinecone.html", "pinecone.async_client", "Async"],
+    ["pinecone.grpc.PineconeGRPC", "pinecone.html", "pinecone.client", ""]
+  ];
+  // Section anchors, which autodoc ids cannot cover: a heading that was renamed,
+  // or one whose content became a page of its own. A value may carry its own
+  // fragment; without one the reader lands at the top of the named page.
   var sections = {
+    "rest.html#db-control-plane": "pinecone.html",
     "rest.html#db-data-plane": "sync-index.html",
+    "rest.html#vectors": "sync-index.html",
+    "rest.html#records": "sync-index.html",
+    "rest.html#namespaces": "sync-index.html",
+    "rest.html#bulk-import": "sync-index.html",
+    "rest.html#restore-jobs": "pinecone.html#restorejobs",
+    "asyncio.html#db-control-plane": "async-pinecone.html",
     "asyncio.html#db-data-plane": "async-index.html",
-    "grpc.html#db-data-plane": "grpc.html"
+    "asyncio.html#vectors": "async-index.html",
+    "asyncio.html#records": "async-index.html",
+    "asyncio.html#namespaces": "async-index.html",
+    "asyncio.html#bulk-import": "async-index.html",
+    "asyncio.html#pineconeasyncio": "async-pinecone.html#asyncpinecone",
+    "asyncio.html#indexes": "async-pinecone.html#asyncindexes",
+    "asyncio.html#collections": "async-pinecone.html#asynccollections",
+    "asyncio.html#backups": "async-pinecone.html#asyncbackups",
+    "asyncio.html#inference": "async-pinecone.html#asyncinference",
+    "asyncio.html#restore-jobs": "async-pinecone.html#asyncrestorejobs",
+    // 10.0 folded PineconeGRPC into Pinecone, so the gRPC page documents only
+    // the index and future classes. Its control-plane anchors belong elsewhere.
+    "grpc.html#pineconegrpc": "pinecone.html",
+    "grpc.html#db-control-plane": "pinecone.html",
+    "grpc.html#indexes": "pinecone.html",
+    "grpc.html#collections": "pinecone.html",
+    "grpc.html#backups": "pinecone.html",
+    "grpc.html#restore-jobs": "pinecone.html#restorejobs",
+    "grpc.html#db-data-plane": "grpc.html",
+    "grpc.html#vectors": "grpc.html",
+    "grpc.html#namespaces": "grpc.html",
+    "admin.html#admin-api": "admin.html#admin"
   };
   var page = window.location.pathname.split("/").pop();
-  var dir = "reference/";
   var moved = sections[page + hash];
   if (target.indexOf("#") !== -1) {
     // The target names its own section; the old fragment has nothing to add.
     hash = "";
   } else if (moved) {
-    target = dir + moved;
+    target = prefix + "reference/" + moved;
     hash = "";
-  } else if (hash && target.indexOf(dir) === 0) {
+  } else if (hash && into) {
     var id = hash.substring(1);
-    for (var i = 0; i < classes.length; i++) {
+    var done = false;
+    // A relocated member is more specific than its class's rename, so it wins.
+    for (var c = 0; c < clients.length && !done; c++) {
+      if (id.indexOf(clients[c][0] + ".") === 0) {
+        var verb = verbs[id.substring(clients[c][0].length + 1)];
+        if (verb) {
+          target = prefix + "reference/" + clients[c][1];
+          hash = "#" + clients[c][2] + "." + verb[0] + "." +
+                 clients[c][3] + resources[verb[0]] + "." + verb[1];
+          done = true;
+        }
+      }
+    }
+    for (var i = 0; i < classes.length && !done; i++) {
       var oldId = classes[i][0];
       if (id === oldId || id.indexOf(oldId + ".") === 0) {
-        target = dir + classes[i][1];
+        target = prefix + "reference/" + classes[i][1];
         hash = "#" + classes[i][2] + id.substring(oldId.length);
-        break;
+        done = true;
       }
     }
   }