Release 0.3.2

docs/source/_static/custom.css

@@ -5,3 +5,7 @@
 .api-generation {
     display: none;
 }
+
+.pyaml-member-summary td p {
+    margin-bottom: 0;
+}

docs/source/conf.py

@@ -4,6 +4,8 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
 
+import re
+
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
@@ -32,16 +34,66 @@
 autodoc_typehints_format = "short"
 # autosummary_generate_overwrite = False
 # autosummary_ignore_module_all = False
-autoclass_content = "both"  # include both class docstring and __init__
+# Class docstrings document the constructor parameters; __init__ docstrings are not rendered.
+autoclass_content = "class"
 
 napoleon_use_rtype = False  # More legible
 # napoleon_numpy_docstring = False  # Force consistency, leave only Google
-# napoleon_custom_sections = [("Returns", "params_style")]
+napoleon_custom_sections = ["Configuration"]
 
 templates_path = ["_templates"]
 exclude_patterns = []
 
 
+# -- Class docstring "Methods"/"Attributes" sections ---------------------------
+# Class docstrings list their methods and attributes so that ``help(obj)`` is
+# self-contained. autodoc already documents each member from its own docstring,
+# so on the rendered page the ``.. method::`` / ``.. attribute::`` blocks that
+# napoleon emits for these sections are collapsed into a linked summary table
+# instead of a second full description of every member.
+
+_MEMBER_DIRECTIVE = re.compile(r"^\.\. (method|attribute):: (\S[^(]*)")
+_SUMMARY_TITLES = {"attribute": ("Attributes", "attr"), "method": ("Methods", "meth")}
+
+
+def _read_member_block(lines, i):
+    """Return ``(kind, member, description, next_index)`` for the directive at ``lines[i]``."""
+    kind, member = _MEMBER_DIRECTIVE.match(lines[i]).groups()
+    description = []
+    i += 1
+    while i < len(lines) and (not lines[i].strip() or lines[i].startswith("   ")):
+        text = lines[i].strip()
+        if text and not text.startswith(":"):  # skip directive options such as ``:type:``
+            description.append(text)
+        i += 1
+    return kind, member.strip(), " ".join(description), i
+
+
+def summarize_member_sections(app, what, name, obj, options, lines):
+    if what != "class":
+        return
+    out = []
+    i = 0
+    while i < len(lines):
+        if not _MEMBER_DIRECTIVE.match(lines[i]):
+            out.append(lines[i])
+            i += 1
+            continue
+        kind = _MEMBER_DIRECTIVE.match(lines[i]).group(1)
+        title, role = _SUMMARY_TITLES[kind]
+        out += [f".. rubric:: {title}", "", ".. list-table::", "   :widths: 30 70", "   :class: pyaml-member-summary", ""]
+        while i < len(lines) and (m := _MEMBER_DIRECTIVE.match(lines[i])) and m.group(1) == kind:
+            _, member, description, i = _read_member_block(lines, i)
+            out += [f"   * - :py:{role}:`~{name}.{member}`", f"     - {description}"]
+        out.append("")
+    lines[:] = out
+
+
+def setup(app):
+    # Run after napoleon (default priority 500), which produces the member directives.
+    app.connect("autodoc-process-docstring", summarize_member_sections, priority=600)
+
+
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 

examples/other_examples/ControlSystem/tango/config.yaml

@@ -8,7 +8,7 @@ controls:
     name: live
 data_folder: /data/store
 devices:
-- type: pyaml.bpm.bpm
+- type: pyaml.diagnostics.bpm.bpm
   name: BPM_C01-01
   x_pos: srdiag/bpm/c01-01/SA_HPosition
   y_pos: srdiag/bpm/c01-01/SA_VPosition

examples/other_examples/ControlSystem/tango/main.py

@@ -3,7 +3,7 @@
 sr = Accelerator.load("config.yaml")
 
 # print the BPM position
-bpm = sr.live.bpm.get("BPM_C01-01")  # bpm is a BPM
+bpm = sr.live.diagnostic.bpm.get("BPM_C01-01")  # bpm is a BPM
 print(bpm.positions.get())
 
 # Direct access to control system

examples/other_examples/ORM_Tango_server/ORM.py

@@ -102,8 +102,8 @@ def orbit_callback(self, action: int, cdata):
 
     def orm_run(self):
         # On design sleep 10ms to allow thread schedule
-        self.SR.design.orm.measure(callback=orbit_callback, sleep_between_meas=0.01)
-        self.orm_data = self.SR.design.orm.get()
+        self.SR.design.tool.orm.measure(callback=orbit_callback, sleep_between_meas=0.01)
+        self.orm_data = self.SR.design.tool.orm.get()
         self.set_status(f"Ready to scan: {self.ConfigFileName}")
         self.set_state(DevState.ON)
 

examples/other_examples/OphydDevice_examples/tune_ophyd_device.py

@@ -179,6 +179,6 @@ def unit(self) -> str:
 
 # Main code
 sr = Accelerator.from_dict(acc_config)
-tm1 = sr.live.get_betatron_tune_monitor("MY_TUNE_MONITOR")
+tm1 = sr.live.diagnostic.get("MY_TUNE_MONITOR")
 print(tm1.tune.get())
 print(tm1.frequency.get())

examples/use_cases/01-tune_correction.py

@@ -80,7 +80,7 @@
 # In[4]:
 
 
-tune_monitor = SR.get_betatron_tune_monitor("BETATRON_TUNE")
+tune_monitor = SR.diagnostic.get("BETATRON_TUNE")
 print(f"Current tune: {tune_monitor.tune.get()}")
 print(tune_monitor)  # string representation
 
@@ -112,14 +112,14 @@
 
 # ### Standard tune correction tool
 #
-# `SR.tune` is the `DEFAULT_TUNE_CORRECTION` tool. `SR.trm` is the `DEFAULT_TUNE_RESPONSE_MATRIX` tool.
+# `SR.tool.tune` is the `DEFAULT_TUNE_CORRECTION` tool. `SR.tool.trm` is the `DEFAULT_TUNE_RESPONSE_MATRIX` tool.
 #
 # Before correcting the tune you need a response matrix. It can be measured (below) or loaded from a previously saved file.
 
 # In[7]:
 
 
-print(SR.tune)  # string representation
+print(SR.tool.tune)  # string representation
 
 
 # #### Measuring the tune response matrix
@@ -145,36 +145,36 @@ def tune_callback(action: int, cb_data: dict):
 # In[9]:
 
 
-if SR.tune.response_matrix is None:
-    SR.trm.measure(sleep_between_step=wait_time, callback=tune_callback)
-    SR.trm.save(CONFIG_DIR / "trm.json")
+if SR.tool.tune.response_matrix is None:
+    SR.tool.trm.measure(sleep_between_step=wait_time, callback=tune_callback)
+    SR.tool.trm.save(CONFIG_DIR / "trm.json")
 
-SR.tune.load(CONFIG_DIR / "trm.json")
+SR.tool.tune.load(CONFIG_DIR / "trm.json")
 print("Response matrix loaded.")
-print(SR.trm)  # string representation
+print(SR.tool.trm)  # string representation
 
 
 # #### Correcting the tune
 #
-# `SR.tune.set([qx, qy])` runs the correction iteratively. The `iter` parameter controls
+# `SR.tool.tune.set([qx, qy])` runs the correction iteratively. The `iter` parameter controls
 # the number of iterations and `wait_time` the settling time between each iteration.
 
 # In[10]:
 
 
-print(f"Tune before correction: {SR.tune.readback()}")
+print(f"Tune before correction: {SR.tool.tune.readback()}")
 
 qx, qy = 0.19, 0.28
 print(f"\nSetting tune to [{qx}, {qy}]")
-SR.tune.set([qx, qy], iter=10, wait_time=wait_time)
-print(f"Tune after correction: {SR.tune.readback()}")
+SR.tool.tune.set([qx, qy], iter=10, wait_time=wait_time)
+print(f"Tune after correction: {SR.tool.tune.readback()}")
 
 qx, qy = 0.21, 0.30
 print(f"\nSetting tune to [{qx}, {qy}]")
-SR.tune.set([qx, qy], iter=10, wait_time=wait_time)
-print(f"Tune after correction: {SR.tune.readback()}")
+SR.tool.tune.set([qx, qy], iter=10, wait_time=wait_time)
+print(f"Tune after correction: {SR.tool.tune.readback()}")
 
-print(SR.tune)  # string representation
+print(SR.tool.tune)  # string representation
 
 
 # In[ ]:

examples/use_cases/02-chromaticity_measurement.ipynb

@@ -267,7 +267,7 @@
     }
    ],
    "source": [
-    "chroma_monitor = SR.get_chromaticity_monitor(\"CHROMATICITY_MONITOR\")\n",
+    "chroma_monitor = SR.tool.get(\"CHROMATICITY_MONITOR\")\n",
     "\n",
     "chroma_monitor.measure(\n",
     "    callback=chroma_callback,\n",

examples/use_cases/02-chromaticity_measurement.py

@@ -109,7 +109,7 @@ def chroma_callback(action: int, cb_data: dict):
 # In[17]:
 
 
-chroma_monitor = SR.get_chromaticity_monitor("CHROMATICITY_MONITOR")
+chroma_monitor = SR.tool.get("CHROMATICITY_MONITOR")
 
 chroma_monitor.measure(
     callback=chroma_callback,