Add BloqExample.docstring (#1536)

Use the functions docstring if using the `@bloq_example` annotation

Author: mpharrigan

dev_tools/ui-export.ipynb

@@ -6,7 +6,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from qualtran.bloqs.factoring.mod_exp import ModExp\n",
+    "from qualtran.bloqs.factoring.rsa import ModExp\n",
     "from qualtran.drawing import get_musical_score_data, draw_musical_score\n",
     "\n",
     "modexp_small = ModExp(base=3, mod=16, exp_bitsize=3, x_bitsize=2048)\n",
@@ -105,6 +105,7 @@
     "        'examples': list(\n",
     "          {\n",
     "            'name': example.name,\n",
+    "            'example_docstring': example.docstring,\n",
     "            'filename': bloq_filename(example.make())\n",
     "          }\n",
     "          for example in bloq_spec.examples\n",
@@ -211,7 +212,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "qualtran",
+   "display_name": "Python 3 (ipykernel)",
    "language": "python",
    "name": "python3"
   },
@@ -225,9 +226,9 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.11.9"
+   "version": "3.11.8"
   }
  },
  "nbformat": 4,
- "nbformat_minor": 2
+ "nbformat_minor": 4
 }

qualtran/_infra/bloq_example.py

@@ -39,6 +39,7 @@ class BloqExample(Generic[_BloqType]):
         name: A name for the bloq instantiation.
         bloq_cls: The `Bloq` class that this instantiation is an instance of.
         generalizer: Passed to `get_bloq_counts_graph` calls for bloq-counts equivalence checking.
+        docstring: An optional one-line description of the example.
     """
 
     _func: Callable[[], _BloqType] = field(repr=False, hash=False)
@@ -47,6 +48,7 @@ class BloqExample(Generic[_BloqType]):
     generalizer: _GeneralizerType = field(
         converter=lambda x: tuple(x) if isinstance(x, Sequence) else x, default=lambda x: x
     )
+    docstring: Optional[str] = None
 
     def make(self) -> _BloqType:
         """Make the bloq."""
@@ -106,6 +108,7 @@ def _inner(func: Callable[[], _BloqType]) -> BloqExample:
             name=_name_from_func_name(func),
             bloq_cls=_bloq_cls_from_func_annotation(func),
             generalizer=generalizer,
+            docstring=func.__doc__,
         )
 
     if _func is None:

qualtran/bloqs/cryptography/rsa/rsa.ipynb

@@ -107,6 +107,7 @@
    },
    "outputs": [],
    "source": [
+    "\"\"\"Modular exponentiation with symbolic attributes.\"\"\"\n",
     "g, N, n_e, n_x = sympy.symbols('g N n_e, n_x')\n",
     "modexp_symb = ModExp(base=g, mod=N, exp_bitsize=n_e, x_bitsize=n_x)"
    ]
@@ -120,6 +121,7 @@
    },
    "outputs": [],
    "source": [
+    "\"\"\"A small-exponent modular exponentiation demo.\"\"\"\n",
     "modexp_small = ModExp(base=4, mod=15, exp_bitsize=3, x_bitsize=2048)"
    ]
   },
@@ -132,6 +134,7 @@
    },
    "outputs": [],
    "source": [
+    "\"\"\"An example modular exponentiation to factor 13 * 17.\"\"\"\n",
     "modexp = ModExp.make_for_shor(big_n=13 * 17, g=9)"
    ]
   },
@@ -318,12 +321,21 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3",
+   "display_name": "Python 3 (ipykernel)",
    "language": "python",
    "name": "python3"
   },
   "language_info": {
-   "name": "python"
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.11.8"
   }
  },
  "nbformat": 4,

qualtran/bloqs/cryptography/rsa/rsa_mod_exp.py

@@ -162,18 +162,21 @@ def _generalize_k(b: Bloq) -> Optional[Bloq]:
 
 @bloq_example(generalizer=(ignore_split_join, _generalize_k))
 def _modexp_small() -> ModExp:
+    """A small-exponent modular exponentiation demo."""
     modexp_small = ModExp(base=4, mod=15, exp_bitsize=3, x_bitsize=2048)
     return modexp_small
 
 
 @bloq_example(generalizer=(ignore_split_join, _generalize_k))
 def _modexp() -> ModExp:
+    """An example modular exponentiation to factor 13 * 17."""
     modexp = ModExp.make_for_shor(big_n=13 * 17, g=9)
     return modexp
 
 
 @bloq_example
 def _modexp_symb() -> ModExp:
+    """Modular exponentiation with symbolic attributes."""
     g, N, n_e, n_x = sympy.symbols('g N n_e, n_x')
     modexp_symb = ModExp(base=g, mod=N, exp_bitsize=n_e, x_bitsize=n_x)
     return modexp_symb