From e63a96410888ab279fe401d8820dd1eec7e56a3e Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 21 Jul 2026 20:54:19 +0000
Subject: [PATCH] fix: render TOC hyperlinks as simple references for PyPI

The TOC generator emitted self-referential indirect hyperlink targets
(`Text <Text_>`_) for each entry. These collide with the identically
named implicit section targets, which newer docutils (used by PyPI's
readme_renderer) rejects with an ERROR, causing the long_description to
fail rendering and the PyPI upload to return HTTP 400.

Emit simple phrase references (`Text`_) that point directly at the
implicit section targets instead. Older docutils tolerated the previous
form, so local rstcheck passed while PyPI upload failed.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PvMnQEiprU5XKUHukXEpAJ
---
 README.rst             | 62 +++++++++++++++++++++---------------------
 generate-readme-toc.js |  2 +-
 2 files changed, 32 insertions(+), 32 deletions(-)

diff --git a/README.rst b/README.rst
index 9207baa3..948a6443 100644
--- a/README.rst
+++ b/README.rst
@@ -29,67 +29,67 @@ accurate and fully typed.
 Contents
 --------
 
-* `Installation <Installation_>`_
+* `Installation`_
 
-* `Usage <Usage_>`_
+* `Usage`_
 
-  * `Examples <Examples_>`_
+  * `Examples`_
 
-    * `List devices <List devices_>`_
+    * `List devices`_
 
-    * `Unlock a door <Unlock a door_>`_
+    * `Unlock a door`_
 
-  * `Authentication Method <Authentication Method_>`_
+  * `Authentication Method`_
 
-    * `API Key <API Key_>`_
+    * `API Key`_
 
-    * `Personal Access Token <Personal Access Token_>`_
+    * `Personal Access Token`_
 
-  * `Action Attempts <Action Attempts_>`_
+  * `Action Attempts`_
 
-  * `Pagination <Pagination_>`_
+  * `Pagination`_
 
-    * `Manually fetch pages with the nextPageCursor <Manually fetch pages with the nextPageCursor_>`_
+    * `Manually fetch pages with the nextPageCursor`_
 
-    * `Resume pagination <Resume pagination_>`_
+    * `Resume pagination`_
 
-    * `Iterate over all resources <Iterate over all resources_>`_
+    * `Iterate over all resources`_
 
-    * `Return all resources across all pages as a list <Return all resources across all pages as a list_>`_
+    * `Return all resources across all pages as a list`_
 
-  * `Interacting with Multiple Workspaces <Interacting with Multiple Workspaces_>`_
+  * `Interacting with Multiple Workspaces`_
 
-  * `Webhooks <Webhooks_>`_
+  * `Webhooks`_
 
-  * `Advanced Usage <Advanced Usage_>`_
+  * `Advanced Usage`_
 
-    * `Setting the endpoint <Setting the endpoint_>`_
+    * `Setting the endpoint`_
 
-* `Development and Testing <Development and Testing_>`_
+* `Development and Testing`_
 
-  * `Quickstart <Quickstart_>`_
+  * `Quickstart`_
 
-  * `Source Code <Source Code_>`_
+  * `Source Code`_
 
-  * `Requirements <Requirements_>`_
+  * `Requirements`_
 
-  * `Tests <Tests_>`_
+  * `Tests`_
 
-  * `Publishing <Publishing_>`_
+  * `Publishing`_
 
-    * `Automatic <Automatic_>`_
+    * `Automatic`_
 
-    * `Manual <Manual_>`_
+    * `Manual`_
 
-* `GitHub Actions <GitHub Actions_>`_
+* `GitHub Actions`_
 
-  * `Secrets for Optional GitHub Actions <Secrets for Optional GitHub Actions_>`_
+  * `Secrets for Optional GitHub Actions`_
 
-* `Contributing <Contributing_>`_
+* `Contributing`_
 
-* `License <License_>`_
+* `License`_
 
-* `Warranty <Warranty_>`_
+* `Warranty`_
 
 Installation
 ------------
diff --git a/generate-readme-toc.js b/generate-readme-toc.js
index 2a0968db..8aa08ef8 100644
--- a/generate-readme-toc.js
+++ b/generate-readme-toc.js
@@ -47,7 +47,7 @@ async function generateTableOfContents(content) {
   headings.forEach((heading) => {
     const indent = '  '.repeat(heading.level - 1)
 
-    toc.push(`${indent}* \`${heading.text} <${heading.text}_>\`_`)
+    toc.push(`${indent}* \`${heading.text}\`_`)
     toc.push('')
   })