Demo notebook fixes (#1626)

doctorperceptron · web-flow · commit 7e608d583cd3 · 2025-12-19T14:32:47.000-05:00
This PR introduces a few fixes for processing the demo scripts into
Jupyter Notebooks:

- Replace direct references to thumbnail images with cloud URL
- Process doc URLs
- A lot of these end with a dollar sign, which can confuse the renderer
into thinking the following text is math. The dollar sign isn't needed
in the URL so we strip it.
- Fix headings
- Some demos have custom classes at the very start of the document.
These aren't used and conflict with the heading, so they are removed.
- Use html for figures
  - This is the only way to apply scaling to the figures. 
- Misc. formatting issues and broken links.

**Note**: I used 50% scaling for inline images and 25% for tables.
_Most_ images are huge, so this seems reasonable, but happy to entertain
other suggestions.
diff --git a/conf.py b/conf.py
@@ -76,17 +76,15 @@
     # all example scripts in the 'examples_dirs' folder will be skiped.
     "filename_pattern": r"\.py$",
     "pypandoc": {
-        "filters": [
+        "filters": [ # These are applied in order
             "./lib/filter_directives.py", 
-            "./lib/filter_figures.py",
             "./lib/filter_links.py",
-            "./lib/filter_tables.py"
+            "./lib/filter_tables.py",
+            "./lib/filter_figures.py",
         ]
     },
     # first notebook cell in generated Jupyter notebooks
     "first_notebook_cell": (
-        "# This cell is added by sphinx-gallery\n"
-        "# It can be customized to whatever you like\n"
         "%matplotlib inline"
     ),
     # thumbnail size
diff --git a/demonstrations_v2/tutorial_dqi/metadata.json b/demonstrations_v2/tutorial_dqi/metadata.json
@@ -8,7 +8,7 @@
     "executable_stable": true,
     "executable_latest": true,
     "dateOfPublication": "2025-09-19T10:00:00+00:00",
-    "dateOfLastModification": "2025-11-26T15:48:14+00:00",
+    "dateOfLastModification": "2025-12-19T00:00:00+00:00",
     "categories": [
         "Algorithms"
     ],
@@ -83,4 +83,4 @@
             "weight": 1.0
         }
     ]
-}
+}
diff --git a/demonstrations_v2/tutorial_grovers_algorithm/metadata.json b/demonstrations_v2/tutorial_grovers_algorithm/metadata.json
@@ -8,7 +8,7 @@
     "executable_stable": true,
     "executable_latest": true,
     "dateOfPublication": "2023-07-03T00:00:00+00:00",
-    "dateOfLastModification": "2025-09-22T15:48:14+00:00",
+    "dateOfLastModification": "2025-12-19T00:00:00+00:00",
     "categories": [
         "Getting Started",
         "Algorithms",
@@ -38,4 +38,4 @@
         }
     ],
     "discussionForumUrl": "https://discuss.pennylane.ai/t/understanding-grover/3340"
-}
+}
diff --git a/demonstrations_v2/tutorial_intro_amplitude_amplification/metadata.json b/demonstrations_v2/tutorial_intro_amplitude_amplification/metadata.json
@@ -11,7 +11,7 @@
     "executable_stable": true,
     "executable_latest": true,
     "dateOfPublication": "2024-05-07T00:00:00+00:00",
-    "dateOfLastModification": "2025-09-22T15:48:14+00:00",
+    "dateOfLastModification": "2025-12-19T00:00:00+00:00",
     "categories": [
         "Quantum Computing",
         "Algorithms"
@@ -84,4 +84,4 @@
             "weight": 1.0
         }
     ]
-}
+}
diff --git a/demonstrations_v2/tutorial_multiclass_classification/demo.py b/demonstrations_v2/tutorial_multiclass_classification/demo.py
@@ -1,6 +1,4 @@
 r"""
-.. _multiclass_margin_classifier:
-
 Multiclass margin classifier
 ============================
 
diff --git a/demonstrations_v2/tutorial_multiclass_classification/metadata.json b/demonstrations_v2/tutorial_multiclass_classification/metadata.json
@@ -8,7 +8,7 @@
     "executable_stable": true,
     "executable_latest": true,
     "dateOfPublication": "2020-04-09T00:00:00+00:00",
-    "dateOfLastModification": "2025-09-22T15:48:14+00:00",
+    "dateOfLastModification": "2025-12-19T00:00:00+00:00",
     "categories": [
         "Algorithms"
     ],
@@ -36,4 +36,4 @@
             "weight": 1.0
         }
     ]
-}
+}
diff --git a/demonstrations_v2/tutorial_neutral_atoms/demo.py b/demonstrations_v2/tutorial_neutral_atoms/demo.py
@@ -1,7 +1,6 @@
-r""".. _neutral:
-
+r"""
 Neutral-atom quantum computers
-=============================
+==============================
 
 .. meta::
     :property="og:description": Learn how neutral atom quantum devices work using code
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-11-10T00:00:00+00:00",
+    "dateOfLastModification": "2025-12-19T00:00:00+00:00",
     "categories": [
         "Quantum Hardware",
         "Quantum Computing"
diff --git a/demonstrations_v2/tutorial_phase_kickback/demo.py b/demonstrations_v2/tutorial_phase_kickback/demo.py
@@ -35,7 +35,7 @@
 #    :align: center
 #    :width: 50%
 #
-# If you want to know more about the details, do not hesitate to consult the node `[P.1] </codebook/09-quantum-phase-estimation/01-catch-the-phase/>`_ of the PennyLane Codebook.
+# If you want to know more about the details, do not hesitate to consult the node `[P.1] <https://pennylane.ai/codebook/quantum-phase-estimation/catch-the-phase>`_ of the PennyLane Codebook.
 
 ######################################################################
 # Setting up PennyLane
diff --git a/demonstrations_v2/tutorial_phase_kickback/metadata.json b/demonstrations_v2/tutorial_phase_kickback/metadata.json
@@ -8,7 +8,7 @@
     "executable_stable": true,
     "executable_latest": true,
     "dateOfPublication": "2023-08-01T00:00:00+00:00",
-    "dateOfLastModification": "2025-10-15T00:00:00+00:00",
+    "dateOfLastModification": "2025-12-19T00:00:00+00:00",
     "categories": [
         "Getting Started",
         "Algorithms",
@@ -37,4 +37,4 @@
             "weight": 1.0
         }
     ]
-}
+}
diff --git a/demonstrations_v2/tutorial_photonics/demo.py b/demonstrations_v2/tutorial_photonics/demo.py
@@ -1,5 +1,4 @@
-r""".. _photonics:
-
+r"""
 Photonic quantum computers
 =============================
 
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-11-10T00:00:00+00:00",
+    "dateOfLastModification": "2025-12-19T00:00:00+00:00",
     "categories": [
         "Quantum Hardware",
         "Quantum Computing"
diff --git a/demonstrations_v2/tutorial_qft/metadata.json b/demonstrations_v2/tutorial_qft/metadata.json
@@ -8,7 +8,7 @@
     "executable_stable": true,
     "executable_latest": true,
     "dateOfPublication": "2024-04-16T00:00:00+00:00",
-    "dateOfLastModification": "2025-09-22T15:48:14+00:00",
+    "dateOfLastModification": "2025-12-19T00:00:00+00:00",
     "categories": [
         "Algorithms",
         "Quantum Computing"
@@ -30,4 +30,4 @@
     "basedOnPapers": [],
     "referencedByPapers": [],
     "relatedContent": []
-}
+}
diff --git a/demonstrations_v2/tutorial_qpe/demo.py b/demonstrations_v2/tutorial_qpe/demo.py
@@ -203,7 +203,7 @@
 -------------
 We already know the three building blocks of QPE; it is time to put them to practice.
 We use a single-qubit :class:`~pennylane.PhaseShift` operator :math:`U = R_{\phi}(2 \pi / 5)`
-and its eigenstate :math:`|1\rangle`` with corresponding phase :math:`\theta=0.2.`
+and its eigenstate :math:`|1\rangle` with corresponding phase :math:`\theta=0.2`.
 
 """
 
diff --git a/demonstrations_v2/tutorial_qpe/metadata.json b/demonstrations_v2/tutorial_qpe/metadata.json
@@ -11,7 +11,7 @@
     "executable_stable": true,
     "executable_latest": true,
     "dateOfPublication": "2024-01-30T00:00:00+00:00",
-    "dateOfLastModification": "2025-12-03T15:48:14+00:00",
+    "dateOfLastModification": "2025-12-19T00:00:00+00:00",
     "categories": [
         "Algorithms",
         "Quantum Computing"
diff --git a/demonstrations_v2/tutorial_sc_qubits/demo.py b/demonstrations_v2/tutorial_sc_qubits/demo.py
@@ -1,5 +1,4 @@
-r""".. _superconducting_qubits:
-
+r"""
 Quantum computing with superconducting qubits
 =============================================
 
diff --git a/demonstrations_v2/tutorial_sc_qubits/metadata.json b/demonstrations_v2/tutorial_sc_qubits/metadata.json
@@ -8,7 +8,7 @@
     "executable_stable": true,
     "executable_latest": true,
     "dateOfPublication": "2022-03-22T00:00:00+00:00",
-    "dateOfLastModification": "2025-10-15T00:00:00+00:00",
+    "dateOfLastModification": "2025-12-19T00:00:00+00:00",
     "categories": [
         "Quantum Hardware",
         "Quantum Computing"
@@ -116,4 +116,4 @@
         }
     ],
     "discussionForumUrl": "https://discuss.pennylane.ai/t/quantum-computing-with-superconducting-qubits-demo/7336"
-}
+}
diff --git a/demonstrations_v2/tutorial_teleportation/metadata.json b/demonstrations_v2/tutorial_teleportation/metadata.json
@@ -8,7 +8,7 @@
     "executable_stable": true,
     "executable_latest": true,
     "dateOfPublication": "2023-10-20T00:00:00+00:00",
-    "dateOfLastModification": "2025-09-22T15:48:14+00:00",
+    "dateOfLastModification": "2025-12-19T00:00:00+00:00",
     "categories": [
         "Getting Started",
         "Quantum Computing"
@@ -73,4 +73,4 @@
             "weight": 1.0
         }
     ]
-}
+}
diff --git a/demonstrations_v2/tutorial_trapped_ions/demo.py b/demonstrations_v2/tutorial_trapped_ions/demo.py
@@ -1,5 +1,4 @@
-r""".. _trapped_ions:
-
+r"""
 Trapped ion quantum computers
 =============================
 
@@ -12,8 +11,6 @@
    tutorial_sc_qubits Quantum computing with superconducting qubits
    tutorial_photonics Photonic quantum computers
 
-*Author: Alvaro Ballon — Posted: 10 November 2021. Last updated: 26 August 2022.*
-
 The race for quantum advantage is on! 
 A host of competitors are using different technologies to build a useful quantum
 computer. Some common approaches are **trapped ions,
diff --git a/demonstrations_v2/tutorial_trapped_ions/metadata.json b/demonstrations_v2/tutorial_trapped_ions/metadata.json
@@ -8,7 +8,7 @@
     "executable_stable": true,
     "executable_latest": true,
     "dateOfPublication": "2021-11-10T00:00:00+00:00",
-    "dateOfLastModification": "2025-10-03T00:00:00+00:00",
+    "dateOfLastModification": "2025-12-19T00:00:00+00:00",
     "categories": [
         "Quantum Hardware",
         "Quantum Computing"
diff --git a/lib/filter_figures.py b/lib/filter_figures.py
@@ -4,18 +4,14 @@
 Pandoc filter to convert figure directives to images.
 """
 
-from pandocfilters import toJSONFilter, Image
-from filter_helpers import parse_img_source
+from pandocfilters import toJSONFilter, RawInline
+from filter_helpers import make_html_figure
 
 
 def filter_images(key, value, format, _):
     if key == 'Image':
         _, _, [url, _] = value
-        cleaned_url = parse_img_source(url)
-
-        alt = { "t": "Str", "c": cleaned_url }
-        
-        return Image(["", [], []], [alt], [cleaned_url, ""])
+        return RawInline("html", make_html_figure(url))
 
 if __name__ == '__main__':
     toJSONFilter(filter_images)
diff --git a/lib/filter_helpers.py b/lib/filter_helpers.py
@@ -3,22 +3,20 @@
 
 ASSETS_DIR = "https://blog-assets.cloud.pennylane.ai/demos/"
 
+def make_html_figure(src: str, width: int = 50) -> str:
+    """Make an HTML figure from a source string.
+    Returns an HTML string for the figure.
+    """
+    cleaned_url = parse_img_source(src)
+    return f"<img src='{cleaned_url}' alt='' style='display:block; margin:auto; width:{width}%;'/>"
+
 def parse_img_source(src: str) -> str:
-    if "/_static/demonstration_assets/" in src:
+    if "/_static/demonstration_assets/" in src or "/_static/demo_thumbnails/" 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.
@@ -49,7 +47,8 @@ def parse_text(key, val, format, meta):
         elif key == 'Space':
             result.append(" ")
         elif key == 'Image':
-            result.append(make_markdown_figure(val))
+            _, _, [url, _] = val
+            result.append(make_html_figure(url, width=25))
             # Don't process the rest of the block
             return []
         elif key == 'Link':
diff --git a/lib/filter_links.py b/lib/filter_links.py
@@ -90,7 +90,9 @@ def filter_links(key, value, format, _):
                 else:
                     name, link = process_link(text, key)
 
-                return Link(["",[],[]], pandocify_string(name), [link,""])
+                # Some links end with a dollar sign for some reason, but this is interpreted as math. 
+                # Remove it to avoid this.
+                return Link(["",[],[]], pandocify_string(name), [link.removesuffix("$"),""])
 
 if __name__ == '__main__':
     pl_obj_inv = make_named_inventory(load_inventory_with_retry(PL_OBJ_INV_URL+"objects.inv"))

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": "2025-09-19T10:00:00+00:00",`
`11`		`- "dateOfLastModification": "2025-11-26T15:48:14+00:00",`
	`11`	`+ "dateOfLastModification": "2025-12-19T00:00:00+00:00",`
`12`	`12`	`"categories": [`
`13`	`13`	`"Algorithms"`
`14`	`14`	`],`
`@@ -83,4 +83,4 @@`
`83`	`83`	`"weight": 1.0`
`84`	`84`	`}`
`85`	`85`	`]`
`86`		`-}`
	`86`	`+}`
Original file line number	Diff line number	Diff line change
`@@ -11,7 +11,7 @@`
`11`	`11`	`"executable_stable": true,`
`12`	`12`	`"executable_latest": true,`
`13`	`13`	`"dateOfPublication": "2024-05-07T00:00:00+00:00",`
`14`		`- "dateOfLastModification": "2025-09-22T15:48:14+00:00",`
	`14`	`+ "dateOfLastModification": "2025-12-19T00:00:00+00:00",`
`15`	`15`	`"categories": [`
`16`	`16`	`"Quantum Computing",`
`17`	`17`	`"Algorithms"`
`@@ -84,4 +84,4 @@`
`84`	`84`	`"weight": 1.0`
`85`	`85`	`}`
`86`	`86`	`]`
`87`		`-}`
	`87`	`+}`
Original file line number	Diff line number	Diff line change
`@@ -35,7 +35,7 @@`
`35`	`35`	`# :align: center`
`36`	`36`	`# :width: 50%`
`37`	`37`	`#`
`38`		-# If you want to know more about the details, do not hesitate to consult the node `[P.1] </codebook/09-quantum-phase-estimation/01-catch-the-phase/>`_ of the PennyLane Codebook.
	`38`	+# If you want to know more about the details, do not hesitate to consult the node `[P.1] <https://pennylane.ai/codebook/quantum-phase-estimation/catch-the-phase>`_ of the PennyLane Codebook.
`39`	`39`
`40`	`40`	`######################################################################`
`41`	`41`	`# Setting up PennyLane`