chore: Rework docs generation (#5481)

* Change docs generation to use id for parent doc instead of slug

* Rename step

.github/workflows/readme_sync.yml

@@ -17,7 +17,7 @@ jobs:
       - name: Checkout this repo
         uses: actions/checkout@v3
 
-      - name: Set up Python 3.8.10
+      - name: Set up Python
         uses: actions/setup-python@v4
         with:
           python-version: "3.10"

docs/pydoc/renderers.py

@@ -18,7 +18,7 @@ title: {title}
 excerpt: {excerpt}
 category: {category}
 slug: {slug}
-parentDocSlug: {parent_doc_slug}
+parentDoc: {parent_doc}
 order: {order}
 hidden: false
 ---
@@ -26,6 +26,15 @@ hidden: false
 """
 
 
+def create_headers(version: str):
+    # Utility function to create Readme.io headers.
+    # We assume the README_API_KEY env var is set since we check outside
+    # to show clearer error messages.
+    README_API_KEY = os.getenv("README_API_KEY")
+    token = base64.b64encode(f"{README_API_KEY}:".encode()).decode()
+    return {"authorization": f"Basic {token}", "x-readme-version": version}
+
+
 @dataclasses.dataclass
 class ReadmeRenderer(Renderer):
     """
@@ -49,8 +58,8 @@ class ReadmeRenderer(Renderer):
 
     def init(self, context: Context) -> None:
         self.markdown.init(context)
-        version = self._doc_version()
-        self.categories = self._readme_categories(version)
+        self.version = self._doc_version()
+        self.categories = self._readme_categories(self.version)
 
     def _doc_version(self) -> str:
         """
@@ -74,8 +83,7 @@ class ReadmeRenderer(Renderer):
             warnings.warn("README_API_KEY env var is not set, using a placeholder category ID")
             return {"haystack-classes": "ID"}
 
-        token = base64.b64encode(f"{README_API_KEY}:".encode()).decode()
-        headers = {"authorization": f"Basic {token}", "x-readme-version": version}
+        headers = create_headers(version)
 
         res = requests.get("https://dash.readme.com/api/v1/categories", headers=headers, timeout=60)
 
@@ -84,6 +92,29 @@ class ReadmeRenderer(Renderer):
 
         return {c["slug"]: c["id"] for c in res.json()}
 
+    def _doc_id(self, doc_slug: str, version: str) -> str:
+        """
+        Fetch the doc id of the given doc slug and version from Readme.io.
+        README_API_KEY env var must be set to correctly get the id.
+        If doc_slug is an empty string return an empty string.
+        """
+        if not doc_slug:
+            # Not all docs have a parent doc, in case we get no slug
+            # we just return an empty string.
+            return ""
+
+        README_API_KEY = os.getenv("README_API_KEY")
+        if not README_API_KEY:
+            warnings.warn("README_API_KEY env var is not set, using a placeholder doc ID")
+            return "fake-doc-id"
+
+        headers = create_headers(version)
+        res = requests.get(f"https://dash.readme.com/api/v1/docs/{doc_slug}", headers=headers, timeout=60)
+        if not res.ok:
+            sys.exit(f"Error requesting {doc_slug} doc for version {version}")
+
+        return res.json()["id"]
+
     def render(self, modules: t.List[docspec.Module]) -> None:
         if self.markdown.filename is None:
             sys.stdout.write(self._frontmatter())
@@ -97,7 +128,7 @@ class ReadmeRenderer(Renderer):
         return README_FRONTMATTER.format(
             title=self.title,
             category=self.categories[self.category_slug],
-            parent_doc_slug=self.parent_doc_slug,
+            parent_doc=self._doc_id(self.parent_doc_slug, self.version),
             excerpt=self.excerpt,
             slug=self.slug,
             order=self.order,