Documentation generation for yellow_pages.py and element_array.py

Author: gupichon-soleil

pyaml/apidoc/gen_api.py

@@ -82,6 +82,7 @@
     "pyaml.tuning_tools.orbit_response_matrix",
     "pyaml.tuning_tools.response_matrix",
     "pyaml.tuning_tools.tune",
+    "pyaml.yellow_pages",
 ]
 
 
@@ -111,27 +112,21 @@ def generate_selective_module(m):
         file.write(f".. automodule:: {p.__name__}\n")
         if len(all_cls) > 0:
             # Exclude classes that will be treated by autoclass
-            file.write(
-                f"   :exclude-members: {','.join([c.__name__ for c in all_cls])}\n\n"
-            )
+            file.write(f"   :exclude-members: {','.join([c.__name__ for c in all_cls])}\n\n")
         for c in all_cls:
             file.write(f"   .. autoclass:: {c.__name__}\n")
             file.write("         :members:\n")
             if m in ["pyaml.arrays.element_array"]:
                 # Include special members for operator overloading
-                file.write(
-                    "         :special-members: __add__, __and__, __or__, __sub__ \n"
-                )
+                file.write("         :special-members: __add__, __and__, __or__, __sub__ \n")
             file.write("         :exclude-members: model_config\n")
             file.write("         :undoc-members:\n")
             file.write("         :show-inheritance:\n\n")
 
 
 def generate_toctree(filename: str, title: str, level: int, module: str):
     sub_modules = [m for m in modules if m.startswith(module)]
-    level_path = sorted(
-        set([m.split(".")[level + 1 : level + 2][0] for m in sub_modules])
-    )
+    level_path = sorted(set([m.split(".")[level + 1 : level + 2][0] for m in sub_modules]))
 
     paths = []
 
@@ -166,9 +161,7 @@ def gen_doc():
     while len(paths) > 0:
         npaths = []
         for p in paths:
-            npaths.extend(
-                generate_toctree(f"api/{'pyaml.' + p}.rst", f"{p}", level, "pyaml." + p)
-            )
+            npaths.extend(generate_toctree(f"api/{'pyaml.' + p}.rst", f"{p}", level, "pyaml." + p))
         paths = npaths
         level += 1
     print("done")

pyaml/arrays/element_array.py

@@ -96,9 +96,7 @@ def __create_array(self, array_name: str, element_type: type, elements: list):
         elif issubclass(element_type, Element):
             return ElementArray(array_name, elements, self.__use_aggregator)
         else:
-            raise PyAMLException(
-                f"Unsupported sliced array for type {str(element_type)}"
-            )
+            raise PyAMLException(f"Unsupported sliced array for type {str(element_type)}")
 
     def __eval_field(self, attribute_name: str, element: Element) -> str:
         function_name = "get_" + attribute_name
@@ -109,16 +107,14 @@ def __ensure_compatible_operand(self, other: object) -> "ElementArray":
         """Validate the operand used for set-like operations between arrays."""
         if not isinstance(other, ElementArray):
             raise TypeError(
-                f"Unsupported operand type(s) for set operation: "
-                f"'{type(self).__name__}' and '{type(other).__name__}'"
+                f"Unsupported operand type(s) for set operation: '{type(self).__name__}' and '{type(other).__name__}'"
             )
 
         if len(self) > 0 and len(other) > 0:
             if self.get_peer() is not None and other.get_peer() is not None:
                 if self.get_peer() != other.get_peer():
                     raise PyAMLException(
-                        f"{self.__class__.__name__}: cannot operate on arrays "
-                        "attached to different peers"
+                        f"{self.__class__.__name__}: cannot operate on arrays attached to different peers"
                     )
         return other
 
@@ -170,9 +166,7 @@ def __is_bool_mask(self, other: object) -> bool:
             pass
 
         # --- python sequence of bools (but not a string/bytes) ---
-        if isinstance(other, Sequence) and not isinstance(
-            other, (str, bytes, bytearray)
-        ):
+        if isinstance(other, Sequence) and not isinstance(other, (str, bytes, bytearray)):
             # Avoid treating ElementArray as a mask
             if isinstance(other, ElementArray):
                 return False
@@ -195,8 +189,7 @@ def __and__(self, other: object):
            If ``other`` is an ElementArray, the result contains elements
            whose names are present in both arrays.
 
-           Example
-           -------
+           **Example**
 
            .. code-block:: python
 
@@ -208,8 +201,8 @@ def __and__(self, other: object):
            If ``other`` is a boolean mask (list[bool] or numpy.ndarray of bool),
            elements are kept where the mask is True.
 
-           Example
-           -------
+           **Example**
+
            .. code-block:: python
 
                >>> mask = cell1.mask_by_type(Magnet)
@@ -232,8 +225,7 @@ def __and__(self, other: object):
             mask = list(other)  # works for list/tuple and numpy arrays
             if len(mask) != len(self):
                 raise ValueError(
-                    f"{self.__class__.__name__}: mask length ({len(mask)}) "
-                    f"does not match array length ({len(self)})"
+                    f"{self.__class__.__name__}: mask length ({len(mask)}) does not match array length ({len(self)})"
                 )
             res = [e for e, keep in zip(self, mask, strict=True) if bool(keep)]
             return self.__auto_array(res)
@@ -261,8 +253,7 @@ def __sub__(self, other: object):
            If ``other`` is an ElementArray, the result contains elements
            whose names are present in ``self`` but not in ``other``.
 
-           Example
-           -------
+           **Example**
 
            .. code-block:: python
 
@@ -275,8 +266,7 @@ def __sub__(self, other: object):
            elements are removed where the mask is True.
            This is the inverse of ``& mask``.
 
-           Example
-           -------
+           **Example**
 
             .. code-block:: python
 
@@ -300,8 +290,7 @@ def __sub__(self, other: object):
             mask = list(other)
             if len(mask) != len(self):
                 raise ValueError(
-                    f"{self.__class__.__name__}: mask length ({len(mask)}) "
-                    f"does not match array length ({len(self)})"
+                    f"{self.__class__.__name__}: mask length ({len(mask)}) does not match array length ({len(self)})"
                 )
             res = [e for e, remove in zip(self, mask, strict=True) if not bool(remove)]
             return self.__auto_array(res)

pyaml/yellow_pages.py

@@ -4,29 +4,29 @@
 Fully dynamic YellowPages service attached to Accelerator.
 
 Key points:
-- Auto-discovery only: arrays, tools and diagnostics are discovered at runtime
-  by scanning all modes.
-- No caching: every call reflects current runtime state.
-- Simple query syntax for identifiers:
-    - wildcard / fnmatch:
-        yp["OH4*"]
-    - regular expression:
-        yp["re:^SH1A-C0[12]-H$"]
+    - Auto-discovery only: arrays, tools and diagnostics are discovered at runtime
+      by scanning all modes.
+    - No caching: every call reflects current runtime state.
+    - Simple query syntax for identifiers:
+        - wildcard / fnmatch:
+            yp["OH4*"]
+        - regular expression:
+            yp["re:^SH1A-C0[12]-H$"]
 
 Expected Accelerator interface
 ------------------------------
-- controls()   -> dict[str, ElementHolder]
-- simulators() -> dict[str, ElementHolder]
-- modes()      -> dict[str, ElementHolder]
+    - controls()   -> dict[str, ElementHolder]
+    - simulators() -> dict[str, ElementHolder]
+    - modes()      -> dict[str, ElementHolder]
 
 Expected ElementHolder interface
 --------------------------------
-- list_arrays() -> set[str]
-- list_tools() -> set[str]
-- list_diagnostics() -> set[str]
-- get_array(name: str) -> Any
-- get_tool(name: str) -> Any
-- get_diagnostic(name: str) -> Any
+    - list_arrays() -> set[str]
+    - list_tools() -> set[str]
+    - list_diagnostics() -> set[str]
+    - get_array(name: str) -> Any
+    - get_tool(name: str) -> Any
+    - get_diagnostic(name: str) -> Any
 """
 
 from __future__ import annotations