From ab4129f2476992dda1cc46fb150ccae15791df00 Mon Sep 17 00:00:00 2001
From: Khaleel Al-Adhami <khaleel.aladhami@gmail.com>
Date: Thu, 2 Apr 2026 13:56:43 -0700
Subject: [PATCH] do not use actual filepath for docgen module

---
 pcweb/docgen_pipeline.py     | 27 ++++++++++++++++-----------
 pcweb/pages/docs/__init__.py |  6 ++++--
 2 files changed, 20 insertions(+), 13 deletions(-)

diff --git a/pcweb/docgen_pipeline.py b/pcweb/docgen_pipeline.py
index de1878b76..1ec41a4a9 100644
--- a/pcweb/docgen_pipeline.py
+++ b/pcweb/docgen_pipeline.py
@@ -169,7 +169,8 @@ class ReflexDocTransformer(DocumentTransformer[rx.Component]):
     the reflex package look identical to the locally-authored ones.
     """
 
-    def __init__(self, filename: str = "") -> None:
+    def __init__(self, virtual_filepath: str = "", filename: str = "") -> None:
+        self.virtual_filepath = virtual_filepath
         self.filename = filename
         self.env: dict = {}
 
@@ -234,7 +235,7 @@ def code_block(self, block: CodeBlock) -> rx.Component:
 
         # ``python exec`` only — execute code, produce nothing visible.
         if language == "python" and "exec" in flags:
-            _exec_code(block.content, self.env, self.filename)
+            _exec_code(block.content, self.env, self.virtual_filepath)
             return rx.fragment()
 
         # ``python eval`` (standalone) — eval and return the component directly.
@@ -378,10 +379,10 @@ def _render_demo(self, content: str, flags: set[str]) -> rx.Component:
 
         try:
             if "exec" in flags:
-                _exec_code(content, self.env, self.filename)
+                _exec_code(content, self.env, self.virtual_filepath)
                 comp = self.env[list(self.env.keys())[-1]]()
             elif "graphing" in flags:
-                _exec_code(content, self.env, self.filename)
+                _exec_code(content, self.env, self.virtual_filepath)
                 comp = self.env[list(self.env.keys())[-1]]()
                 parts = content.rpartition("def")
                 data, code = parts[0], parts[1] + parts[2]
@@ -393,7 +394,7 @@ def _render_demo(self, content: str, flags: set[str]) -> rx.Component:
                 comp = eval(content, self.env, self.env)
         except Exception as e:
             e.add_note(
-                f"While rendering demo block in {self.filename}:\n{content[:200]}"
+                f"While rendering demo block in {self.virtual_filepath}:\n{content[:200]}"
             )
             raise
 
@@ -416,10 +417,10 @@ def _render_demo_only(self, content: str, flags: set[str]) -> rx.Component:
 
         try:
             if "exec" in flags:
-                _exec_code(content, self.env, self.filename)
+                _exec_code(content, self.env, self.virtual_filepath)
                 comp = self.env[list(self.env.keys())[-1]]()
             elif "graphing" in flags:
-                _exec_code(content, self.env, self.filename)
+                _exec_code(content, self.env, self.virtual_filepath)
                 comp = self.env[list(self.env.keys())[-1]]()
                 parts = content.rpartition("def")
                 data, code = parts[0], parts[1] + parts[2]
@@ -430,7 +431,7 @@ def _render_demo_only(self, content: str, flags: set[str]) -> rx.Component:
                 comp = eval(content, self.env, self.env)
         except Exception as e:
             e.add_note(
-                f"While rendering demo-only block in {self.filename}:\n{content[:200]}"
+                f"While rendering demo-only block in {self.virtual_filepath}:\n{content[:200]}"
             )
             raise
 
@@ -681,10 +682,14 @@ def _parse_doc(filepath: str | Path) -> Document:
     return parse_document(source)
 
 
-def render_docgen_document(filepath: str | Path) -> rx.Component:
+def render_docgen_document(
+    virtual_filepath: str | Path, actual_filepath: str | Path
+) -> rx.Component:
     """Parse and render a doc file from the reflex package using reflex_docgen."""
-    doc = _parse_doc(filepath)
-    transformer = ReflexDocTransformer(filename=str(filepath))
+    doc = _parse_doc(actual_filepath)
+    transformer = ReflexDocTransformer(
+        virtual_filepath=str(virtual_filepath), filename=str(actual_filepath)
+    )
     return transformer.transform(doc)
 
 
diff --git a/pcweb/pages/docs/__init__.py b/pcweb/pages/docs/__init__.py
index c011c69e1..2b0b9f979 100644
--- a/pcweb/pages/docs/__init__.py
+++ b/pcweb/pages/docs/__init__.py
@@ -273,9 +273,11 @@ def get_component_docgen(virtual_doc: str, actual_path: str, title: str):
     if virtual_doc.startswith("docs/library"):
         return handle_library_doc(virtual_doc, actual_path, title, resolved)
 
-    def comp(_actual=actual_path):
+    def comp(_actual=actual_path, _virtual=virtual_doc):
         toc = get_docgen_toc(_actual)
-        rendered = render_docgen_document(_actual)
+        rendered = render_docgen_document(
+            virtual_filepath=_virtual, actual_filepath=_actual
+        )
         return (toc, rendered)
 
     return make_docpage(resolved.route, resolved.display_title, virtual_doc, comp)