Fix notebook tables (#1596)

doctorperceptron · web-flow · commit 1b6f60893e66 · 2025-11-10T22:15:06.000Z
This PR adds a new [Pandoc filter](https://github.com/jgm/pandocfilters/tree/master) to process the rst tables in the demos and convert them into Markdown for the notebooks. Conversion of the demos with tables has been tested locally. The demos with tables are: - ahs_aquila - tutorial_measurement_optimize - tutorial_neutral_atoms - tutorial_photonics - tutorial_quantum_transfer_learning - tutorial_unitary_synthesis_kak <img width="595" height="312" alt="Screenshot 2025-11-10 at 3 07 46 PM" src="https://github.com/user-attachments/assets/18279771-6fd0-4541-b75f-67395e280b36" /> <img width="557" height="249" alt="Screenshot 2025-11-10 at 3 07 57 PM" src="https://github.com/user-attachments/assets/61a02139-7d10-4721-9e73-ab0ee15b6dc6" /> Notes: - Handles figures, links, and math in tables and headers. - Handles (optional) table caption. - Handles Sphinx Gallery code execution outputs in a cleaner way. These are now added as a code block and the auto-generated Sphinx text (`sphx-glr-script-out`) is removed. - Two demos had HTML formatting set for the tables (which breaks the filter). I [tested removing this](https://pennylane.ai/qml/demonstrations?pr=1596) and it has no effect, since we do all the rendering on the website anyway. - The filter responsible for replacing images with URLs to the cloud-hosted version wasn't working. It is now fixed. - Some refactoring done to move a few things into a helper file for the filters.
diff --git a/conf.py b/conf.py
@@ -79,7 +79,8 @@
         "filters": [
             "./lib/filter_directives.py", 
             "./lib/filter_figures.py",
-            "./lib/filter_links.py"
+            "./lib/filter_links.py",
+            "./lib/filter_tables.py"
         ]
     },
     # first notebook cell in generated Jupyter notebooks
diff --git a/demonstrations_v2/ahs_aquila/metadata.json b/demonstrations_v2/ahs_aquila/metadata.json
@@ -8,7 +8,7 @@
     "executable_stable": false,
     "executable_latest": false,
     "dateOfPublication": "2023-05-16T00:00:00+00:00",
-    "dateOfLastModification": "2025-10-15T00:00:00+00:00",
+    "dateOfLastModification": "2025-11-10T00:00:00+00:00",
     "categories": [
         "Quantum Hardware",
         "Devices and Performance",
@@ -81,4 +81,4 @@
             "logo": "/_static/hardware_logos/aws.png"
         }
     ]
-}
+}
diff --git a/demonstrations_v2/tutorial_measurement_optimize/demo.py b/demonstrations_v2/tutorial_measurement_optimize/demo.py
@@ -335,21 +335,6 @@ def cost_circuit(params):
 # find the gates to rotate the circuit into the shared eigenbasis. To do so, we simply rotate
 # each qubit one-by-one depending on the Pauli operator we are measuring on that wire:
 #
-# .. raw:: html
-#
-#     <style>
-#         .docstable {
-#             max-width: 300px;
-#         }
-#         .docstable tr.row-even th, .docstable tr.row-even td {
-#             text-align: center;
-#         }
-#         .docstable tr.row-odd th, .docstable tr.row-odd td {
-#             text-align: center;
-#         }
-#     </style>
-#     <div class="d-flex justify-content-center">
-#
 # .. rst-class:: docstable
 #
 #     +------------------+-------------------------------+
@@ -364,10 +349,6 @@ def cost_circuit(params):
 #     | :math:`I`        | :math:`I`                     |
 #     +------------------+-------------------------------+
 #
-# .. raw:: html
-#
-#     </div>
-#
 # Therefore, in this particular example:
 #
 # * Wire 0: we are measuring both terms in the :math:`X` basis, apply the Hadamard gate
diff --git a/demonstrations_v2/tutorial_measurement_optimize/metadata.json b/demonstrations_v2/tutorial_measurement_optimize/metadata.json
@@ -8,7 +8,7 @@
     "executable_stable": true,
     "executable_latest": true,
     "dateOfPublication": "2021-01-18T00:00:00+00:00",
-    "dateOfLastModification": "2025-10-15T00:00:00+00:00",
+    "dateOfLastModification": "2025-11-10T00:00:00+00:00",
     "categories": [
         "Quantum Chemistry"
     ],
@@ -96,4 +96,4 @@
             "weight": 1.0
         }
     ]
-}
+}
diff --git a/demonstrations_v2/tutorial_neutral_atoms/demo.py b/demonstrations_v2/tutorial_neutral_atoms/demo.py
@@ -676,21 +676,6 @@ def neutral_atom_CZ(distance, coupling):
 #
 # The net effect of the sequence of pulses is summarized in the following table.
 #
-# .. raw:: html
-#
-#     <style>
-#         .docstable {
-#             max-width: 300px;
-#         }
-#         .docstable tr.row-even th, .docstable tr.row-even td {
-#             text-align: center;
-#         }
-#         .docstable tr.row-odd th, .docstable tr.row-odd td {
-#             text-align: center;
-#         }
-#     </style>
-#     <div class="d-flex justify-content-center">
-#
 # .. rst-class:: docstable
 #
 #     +-------------------------+-------------------------------+
@@ -705,10 +690,6 @@ def neutral_atom_CZ(distance, coupling):
 #     | :math:`\vert 11\rangle` | :math:`\vert 11\rangle`       |
 #     +-------------------------+-------------------------------+
 #
-# .. raw:: html
-#
-#     </div>
-#
 # Up to a global phase, this corresponds to the :math:`CZ` gate. Together with the :math:`RX` and :math:`RY` gates, we have a universal set of gates,
 # since the `CNOT` gate can be expressed in terms of :math:`CZ` via the equation
 #
diff --git a/demonstrations_v2/tutorial_neutral_atoms/metadata.json b/demonstrations_v2/tutorial_neutral_atoms/metadata.json
@@ -8,7 +8,7 @@
     "executable_stable": true,
     "executable_latest": true,
     "dateOfPublication": "2023-05-30T00:00:00+00:00",
-    "dateOfLastModification": "2025-10-15T00:00:00+00:00",
+    "dateOfLastModification": "2025-11-10T00:00:00+00:00",
     "categories": [
         "Quantum Hardware",
         "Quantum Computing"
@@ -134,4 +134,4 @@
             "weight": 1.0
         }
     ]
-}
+}
diff --git a/demonstrations_v2/tutorial_photonics/metadata.json b/demonstrations_v2/tutorial_photonics/metadata.json
@@ -8,7 +8,7 @@
     "executable_stable": true,
     "executable_latest": true,
     "dateOfPublication": "2022-05-31T00:00:00+00:00",
-    "dateOfLastModification": "2025-10-15T00:00:00+00:00",
+    "dateOfLastModification": "2025-11-10T00:00:00+00:00",
     "categories": [
         "Quantum Hardware",
         "Quantum Computing"
@@ -141,4 +141,4 @@
         }
     ],
     "discussionForumUrl": "https://discuss.pennylane.ai/t/photonic-quantum-computers-demo/7335"
-}
+}
diff --git a/demonstrations_v2/tutorial_quantum_transfer_learning/demo.py b/demonstrations_v2/tutorial_quantum_transfer_learning/demo.py
@@ -64,17 +64,17 @@
 
 .. rst-class:: docstable
 
-+-----------+-----------+-----------------------------------------------------+
-| Network A | Network B | Transfer learning scheme                            |
-+===========+===========+=====================================================+
-| Classical | Classical | CC - Standard classical method. See e.g., Ref. [2]. |
-+-----------+-----------+-----------------------------------------------------+
-| Classical | Quantum   | CQ - **Hybrid model presented in this tutorial.**   |
-+-----------+-----------+-----------------------------------------------------+
-| Quantum   | Classical | QC - Model studied in Ref. [1].                     |
-+-----------+-----------+-----------------------------------------------------+
-| Quantum   | Quantum   | QQ - Model studied in Ref. [1].                     |
-+-----------+-----------+-----------------------------------------------------+
+    +-----------+-----------+-----------------------------------------------------+
+    | Network A | Network B | Transfer learning scheme                            |
+    +===========+===========+=====================================================+
+    | Classical | Classical | CC - Standard classical method. See e.g., Ref. [2]. |
+    +-----------+-----------+-----------------------------------------------------+
+    | Classical | Quantum   | CQ - **Hybrid model presented in this tutorial.**   |
+    +-----------+-----------+-----------------------------------------------------+
+    | Quantum   | Classical | QC - Model studied in Ref. [1].                     |
+    +-----------+-----------+-----------------------------------------------------+
+    | Quantum   | Quantum   | QQ - Model studied in Ref. [1].                     |
+    +-----------+-----------+-----------------------------------------------------+
 
 Classical-to-quantum transfer learning
 --------------------------------------
diff --git a/demonstrations_v2/tutorial_quantum_transfer_learning/metadata.json b/demonstrations_v2/tutorial_quantum_transfer_learning/metadata.json
@@ -8,7 +8,7 @@
     "executable_stable": true,
     "executable_latest": true,
     "dateOfPublication": "2019-12-19T00:00:00+00:00",
-    "dateOfLastModification": "2025-09-22T15:48:14+00:00",
+    "dateOfLastModification": "2025-11-10T11:00:00+00:00",
     "categories": [
         "Quantum Machine Learning"
     ],
@@ -63,4 +63,4 @@
     "referencedByPapers": [],
     "relatedContent": [],
     "discussionForumUrl": "https://discuss.pennylane.ai/t/can-quantum-transfer-learning-be-used-for-multi-classification/3963"
-}
+}
diff --git a/demonstrations_v2/tutorial_unitary_synthesis_kak/metadata.json b/demonstrations_v2/tutorial_unitary_synthesis_kak/metadata.json
@@ -8,7 +8,7 @@
     "executable_stable": true,
     "executable_latest": true,
     "dateOfPublication": "2025-05-30T09:00:00+00:00",
-    "dateOfLastModification": "2025-09-22T15:48:14+00:00",
+    "dateOfLastModification": "2025-11-10T00:00:00+00:00",
     "categories": [
         "Quantum Computing"
     ],
@@ -118,4 +118,4 @@
             "weight": 1.0
         }
     ]
-}
+}
diff --git a/documentation/reference_demo/demo.py b/documentation/reference_demo/demo.py
@@ -1,26 +1,22 @@
 r""" Reference Demo - a.k.a. the kitchen sink
 =============================================
 
-All the restructured text directives we support appear in this demo. If you find a new one, please add it here.
+All the restructured text directives we handle appear in this demo. If you find a new one, please add it here.
 
-Complete list of reStructuredText directive types covered in this demo:  
+Currently handled reStructuredText directives covered in this demo:  
 
-5. math
-3. figure
-6. meta
-9. related
-7. note
-11. tip
-13. warning
+1. math
+2. figure
+3. meta
+4. related
+5. note
+6. tip
+7. warning
 8. raw
-1. admonition
+9. admonition
 
-Unsupported directives:  
-
-4. image(7) -> change to figure  
-12. topic (1) -> change to admonition with class note(?)  
-2. container (3) -> Doesn't work. Remove?  
-10. role (5) -> Remove?  
+Note that we say "handle" rather than "support" because in some cases there are no equivalent markdown constructs.
+In those cases the directive will not appear 1-to-1 in the rendered demo.
 """
 
 # %%
@@ -546,6 +542,39 @@
 #         </div>
 #     </center>
 
+# %%
+# DocTable directive
+# -------------------
+# 
+# This directive is used to create a table.
+#
+# .. rst-class:: docstable
+#
+#    +---------------------+----------------------------------------------------------------------------+----------------------------------------------------------------------------+
+#    | .. centered::       | .. centered::                                                              | .. centered::                                                              |
+#    |  Element Name       |  Diagram Column Here                                                       |   Description of the Thing                                                 |
+#    +=====================+============================================================================+============================================================================+
+#    | Waveguide           | .. figure:: ../_static/demonstration_assets/reference_demo/xanadu_x.png    | A long strip of material that contains and guides                          |
+#    |                     |    :align: center                                                          | electromagentic waves. For example, an optical fibre is a type             |
+#    |                     |    :width: 70%                                                             | of waveguide.                                                              |
+#    +---------------------+----------------------------------------------------------------------------+----------------------------------------------------------------------------+
+#    | Phase-shifter       | .. figure:: ../_static/demonstration_assets/reference_demo/xanadu_x.png    | A piece of material that changes the phase of light. The figure            |
+#    |                     |    :align: center                                                          | shows a particular implementation known as a thermo-optic phase            |
+#    |                     |    :width: 70%                                                             | shifter [#Sabouri2021]_, which is a (sometimes curved) waveguide           |
+#    |                     |                                                                            | that changes properties when heated up using a resistor.                   |
+#    |                     |                                                                            | This allows us to control the applied phase difference.                    |
+#    +---------------------+----------------------------------------------------------------------------+----------------------------------------------------------------------------+
+#    | Beamsplitter        | .. figure:: ../_static/demonstration_assets/reference_demo/xanadu_x.png    | An element with two input and two output qumodes. It transmits a           |
+#    |                     |    :align: center                                                          | fraction :math:`T` of the photons coming in through either entry           |
+#    |                     |    :width: 100%                                                            | port, and reflects a fraction :math:`R=1-T.` The input qumodes can         |
+#    |                     |                                                                            | be combined to create entangled states across the output ports.            |
+#    |                     |                                                                            | In a photonic quantum computing chip, a `directional coupler               |
+#    |                     |                                                                            | <https://en.wikipedia.org/wiki/Power_dividers_and_directional_couplers>`__ |
+#    |                     |                                                                            | is used.                                                                   |
+#    +---------------------+----------------------------------------------------------------------------+----------------------------------------------------------------------------+
+#
+#    This is a caption for the table. It's optional.
+
 # %%
 # NOTES, TIPS, WARNINGS, AND ADMONITIONS
 # --------------------------------------
@@ -636,3 +665,16 @@ def circuit():
     return qml.state()
 
 print(circuit())
+
+# %%
+# Sphinx Gallery Code Block
+# -------------------------
+#
+# These should be converted to regular code blocks.
+#
+# .. rst-class:: sphx-glr-script-out
+#
+#     .. code-block:: none
+#
+#         Some output from sphinx gallery execution goes here.
+#
diff --git a/lib/filter_directives.py b/lib/filter_directives.py
@@ -10,11 +10,20 @@
 
 DEMOS_URL = "https://pennylane.ai/qml/demos/"
 
+
 def filter_directives(key, value, format, _):
     if key == 'Div':
         [[_, classes, _], body] = value
         if "related" in classes or "meta" in classes:
             return []
+        elif "rst-class" in classes:
+            metadata = body[0]
+            content = body[1]
+            rst_class_type = metadata.get("c")[0].get("c")
+            if rst_class_type == "sphx-glr-script-out":
+                return content
+            else:
+                return
         else:
             return BlockQuote(body)
 
diff --git a/lib/filter_figures.py b/lib/filter_figures.py
@@ -4,16 +4,9 @@
 Pandoc filter to convert figure directives to images.
 """
 
-import os
 from pandocfilters import toJSONFilter, Image
+from filter_helpers import parse_img_source
 
-ASSETS_DIR = "https://blog-assets.cloud.pennylane.ai/demos/"
-
-def parse_img_source(src: str) -> str:
-    if "../_static/" in src:
-        return src.replace("../_", ASSETS_DIR + os.getenv("CURRENT_DEMO") + "/main/_assets/")
-    else:
-        return src
 
 def filter_images(key, value, format, _):
     if key == 'Image':
diff --git a/lib/filter_helpers.py b/lib/filter_helpers.py
@@ -0,0 +1,60 @@
+import os
+from pandocfilters import stringify, walk
+
+ASSETS_DIR = "https://blog-assets.cloud.pennylane.ai/demos/"
+
+def parse_img_source(src: str) -> str:
+    if "/_static/demonstration_assets/" in src:
+        img = src.split("/")[-1]
+        return ASSETS_DIR + os.getenv("CURRENT_DEMO") + "/main/_assets/images/" + img
+    else:
+        return src
+
+def make_markdown_figure(figure: list) -> str:
+    """Make a markdown figure from a figure block.
+    Returns a markdown text string for the figure.
+    The format for the figure block is a list containing three elements:
+    [metadata, [url_dict], [url, alt_text]]
+    """
+    [_, [url_dict], _] = figure
+    return f"![]({url_dict.get('c', '')})"
+
+def make_markdown_link(link: list) -> str:
+    """Make a markdown link from a link block.
+    Returns a markdown text string for the link.
+    The format for the link block is a list containing three elements:
+    [metadata, link_text, [link_url, caption]]
+    """
+    [_, link_text, link_url] = link
+    text = stringify(link_text)
+    url = link_url[0]
+    return f"[{text}]({url})"
+
+def process_text(text):
+    """Process a block of 'text'.
+    Return a markdown text string representing the content.
+    """
+    result = []
+    def parse_text(key, val, format, meta):
+        if key in ['Str', 'MetaString']:
+            result.append(val)
+        elif key == 'Code':
+            result.append(val[1])
+        elif key == 'Math':
+            result.append(f"${val[1]}$")
+        elif key == 'LineBreak':
+            result.append(" ")
+        elif key == 'SoftBreak':
+            result.append(" ")
+        elif key == 'Space':
+            result.append(" ")
+        elif key == 'Image':
+            result.append(make_markdown_figure(val))
+            # Don't process the rest of the block
+            return []
+        elif key == 'Link':
+            result.append(make_markdown_link(val))
+            # Don't process the rest of the block
+            return []
+    walk(text, parse_text, "", {})
+    return ''.join(result)
diff --git a/lib/filter_tables.py b/lib/filter_tables.py

Original file line number	Diff line number	Diff line change
`@@ -8,7 +8,7 @@`
`8`	`8`	`"executable_stable": false,`
`9`	`9`	`"executable_latest": false,`
`10`	`10`	`"dateOfPublication": "2023-05-16T00:00:00+00:00",`
`11`		`- "dateOfLastModification": "2025-10-15T00:00:00+00:00",`
	`11`	`+ "dateOfLastModification": "2025-11-10T00:00:00+00:00",`
`12`	`12`	`"categories": [`
`13`	`13`	`"Quantum Hardware",`
`14`	`14`	`"Devices and Performance",`
`@@ -81,4 +81,4 @@`
`81`	`81`	`"logo": "/_static/hardware_logos/aws.png"`
`82`	`82`	`}`
`83`	`83`	`]`
`84`		`-}`
	`84`	`+}`
Original file line number	Diff line number	Diff line change
`@@ -8,7 +8,7 @@`
`8`	`8`	`"executable_stable": true,`
`9`	`9`	`"executable_latest": true,`
`10`	`10`	`"dateOfPublication": "2021-01-18T00:00:00+00:00",`
`11`		`- "dateOfLastModification": "2025-10-15T00:00:00+00:00",`
	`11`	`+ "dateOfLastModification": "2025-11-10T00:00:00+00:00",`
`12`	`12`	`"categories": [`
`13`	`13`	`"Quantum Chemistry"`
`14`	`14`	`],`
`@@ -96,4 +96,4 @@`
`96`	`96`	`"weight": 1.0`
`97`	`97`	`}`
`98`	`98`	`]`
`99`		`-}`
	`99`	`+}`