Fixed docstring to avoid duplicate warning in BPM

Author: JeanLucPons

docs/gen_api.py

@@ -132,7 +132,7 @@ def generate_toctree(filename: str, title: str, level: int, module: str):
         file.write(".. toctree::\n")
 
         file.write("   :maxdepth: 1\n")
-        file.write("   :caption: PyAML packages:\n\n")
+        file.write(f"   :caption: {title}:\n\n")
 
         for p in level_path:
             module_name = module + "." + p

pyaml/accelerator.py

@@ -42,7 +42,7 @@ class ConfigModel(BaseModel):
         Element family
     description : str , optional
         Acceleration description
-    devices : list[Element]
+    devices : list[.common.element.Element]
         Element list
     """
 

pyaml/arrays/array.py

@@ -11,12 +11,14 @@
 
 class ArrayConfigModel(BaseModel):
     """
-    Base class for array configuration
+    Base class for configuration of array of :py:class:`~pyaml.arrays.element.Element`,
+    :py:class:`~pyaml.arrays.bpm.BPM`, :py:class:`~pyaml.arrays.magnet.Magnet` or
+    :py:class:`~pyaml.arrays.cfm_magnet.CombinedFunctionMagnet`.
 
     Parameters
     ----------
     name : str
-        Family name
+        Name of the array
     elements : list[str]
         List of pyaml element names
     """
@@ -37,12 +39,15 @@ def __init__(self, cfg: ArrayConfigModel):
 
     def fill_array(self, holder: ElementHolder):
         """
-        Fill array with elements from the holder.
+        Fill array with elements from the holder and add the array to
+        the holder.
 
         Parameters
         ----------
         holder : ElementHolder
-            The element holder to populate
+            The element holder (:py:class:`~pyaml.lattice.simulator.Simulator`
+            or :py:class:`~pyaml.control.controlsystem.ControlSystem`) to
+            populate with the array.
 
         Raises
         ------

pyaml/arrays/bpm.py

@@ -6,12 +6,12 @@
 
 
 class ConfigModel(ArrayConfigModel):
-    """Configuration model for BPM array."""
+    """Configuration model for :py:class:`.BPMArray`."""
 
 
 class BPM(ArrayConfig):
     """
-    BPM array configuration
+    :py:class:`.BPMArray` configuration.
 
     Example
     -------
@@ -27,7 +27,8 @@ class BPM(ArrayConfig):
             - BPM_C04-02
             - BPM_C04-03
 
-    A BPM array configuration can also be created by code using the following example:
+    A :py:class:`.BPMArray` configuration can also be created by code using the
+    following example:
 
     .. code-block:: python
 
@@ -44,8 +45,11 @@ def __init__(self, cfg: ArrayConfigModel):
 
     def fill_array(self, holder: ElementHolder):
         """
-        Fill the :py:class:`.BPMArray` using element holder. This method is called
-        when an :py:class:`~pyaml.accelerator.Accelerator` is loaded but can be
+        Fill the :py:class:`.BPMArray` using element holder
+        (:py:class:`~pyaml.lattice.simulator.Simulator`
+        or :py:class:`~pyaml.control.controlsystem.ControlSystem`)
+        and add the array to the holder. This method is called when an
+        :py:class:`~pyaml.accelerator.Accelerator` is loaded but can be
         used to create arrays by code as shown bellow:
 
         .. code-block:: python
@@ -60,6 +64,6 @@ def fill_array(self, holder: ElementHolder):
         Parameters
         ----------
         holder : ElementHolder
-            The element holder to populate the BPM array with
+            The element holder to populate the :py:class:`.BPMArray` with.
         """
         holder.fill_bpm_array(self._cfg.name, self._cfg.elements)

pyaml/arrays/bpm_array.py

@@ -18,7 +18,7 @@ class RWBPMPosition(ReadFloatArray):
     ----------
     name : str
         Name of the position accessor
-    bpms : list[BPM]
+    bpms : list[pyaml.bpm.bpm.BPM]
         List of BPM objects to access
     """
 
@@ -80,7 +80,7 @@ class RWBPMSinglePosition(ReadFloatArray):
     ----------
     name : str
         Name of the position accessor
-    bpms : list[BPM]
+    bpms : list[pyaml.bpm.bpm.BPM]
         List of BPM objects to access
     idx : int
         Index for the position axis (0 for horizontal, 1 for vertical)
@@ -134,23 +134,25 @@ def set_aggregator(self, agg: DeviceAccessList):
 
 class BPMArray(ElementArray):
     """
-    Class that implements access to a BPM array
+    Class that implements access to a BPM array.
 
     Parameters
     ----------
     arrayName : str
         Array name
-    bpms : list[BPM]
+    bpms : list[pyaml.bpm.bpm.BPM]
         BPM list, all elements must be attached to the same instance of
-        either a Simulator or a ControlSystem.
+        either a (:py:class:`~pyaml.lattice.simulator.Simulator`
+        or a :py:class:`~pyaml.control.controlsystem.ControlSystem`).
     use_aggregator : bool
         Use aggregator to increase performance by using paralell
         access to underlying devices.
 
     Example
     -------
 
-    An array can be retrieved from the configuration as in the following example:
+    An array can be retrieved from the configuration as in the following
+    example:
 
     .. code-block:: python