make docstring hint more explicit for spacial modulation and duplicat…

…e waveform (#362)

Co-authored-by: Kai-Hsin Wu <khwu@KHWus-MacBook-Pro.local>

src/bloqade/builder/location.py

@@ -15,34 +15,7 @@ def __init__(self, parent: Builder, label: int) -> None:
 
     def scale(self, scale: float):
         """
-        - Scale the preceeding waveform by the specified factor.
-        - Possible Next <Location>:
-
-            -> `...location(int).location(int)`
-                :: keep adding location into current list
-
-        - Possible Next <WaveForm>:
-
-            -> `...location(int).linear()`
-                :: apply linear waveform
-
-            -> `...location(int).constant()`
-                :: apply constant waveform
-
-            -> `...location(int).ploy()`
-                :: apply polynomial waveform
-
-            -> `...location(int).apply()`
-                :: apply pre-constructed waveform
-
-            -> `...location(int).piecewise_linear()`
-                :: apply piecewise linear waveform
-
-            -> `...location(int).piecewise_constant()`
-                :: apply piecewise constant waveform
-
-            -> `...location(int).fn()`
-                :: apply callable as waveform.
+        Scale the preceeding waveform by the specified factor.
 
         Args:
             scale (float): The factor to scale (amplitude of)
@@ -67,20 +40,69 @@ def scale(self, scale: float):
             >>> reg = bloqade.start.add_positions([(0,0),(1,1),(2,2),(3,3)])
             >>> scaled = reg.rydberg.detuning.location(0).location(1).scale(1.2)
 
+
+        - Possible Next <Location>:
+
+            -> `...scale(float).location(int)`
+                :: keep adding location into current list
+
+        - Possible Next <WaveForm>:
+
+            -> `...scale(float).linear()`
+                :: apply linear waveform
+
+            -> `...scale(float).constant()`
+                :: apply constant waveform
+
+            -> `...scale(float).ploy()`
+                :: apply polynomial waveform
+
+            -> `...scale(float).apply()`
+                :: apply pre-constructed waveform(s)
+
+            -> `...scale(float).piecewise_linear()`
+                :: apply piecewise linear waveform
+
+            -> `...scale(float).piecewise_constant()`
+                :: apply piecewise constant waveform
+
+            -> `...scale(float).fn()`
+                :: apply callable as waveform.
+
+
+
         """
         return Scale(self, scale)
 
     def location(self, label: int):
         """
         Append another location to the current location(s)
 
+        Args:
+            label (int): The label of the location
+
+        Examples:
+
+            - Append location 1 to the current location 0.
+
+            >>> reg = bloqade.start.add_positions([(0,0),(1,1),(2,2),(3,3)])
+            >>> loc = reg.rydberg.detuning.location(0)
+            >>> loc = loc.location(1)
+
+            - One can keep appending by concatenating location()
+
+            >>> reg = bloqade.start.add_positions([(0,0),(1,1),(2,2),(3,3)])
+            >>> loc = reg.rydberg.detuning.location(0)
+            >>> loc = loc.location(1).location(2)
+
         - Possible Next <Location>:
 
             -> `...location(int).location(int)`
                 :: keep adding location into current list
 
             -> `...location(int).scale(float)`
-                :: specify scaling factor for the preceeding waveform
+                :: specify scaling factor to current location
+                for the preceeding waveform
 
         - Possible Next <WaveForm>:
 
@@ -105,22 +127,6 @@ def location(self, label: int):
             -> `...location(int).fn()`
                 :: apply callable as waveform.
 
-        Args:
-            label (int): The label of the location
-
-        Examples:
-
-            - Append location 1 to the current location 0.
-
-            >>> reg = bloqade.start.add_positions([(0,0),(1,1),(2,2),(3,3)])
-            >>> loc = reg.rydberg.detuning.location(0)
-            >>> loc = loc.location(1)
-
-            - One can keep appending by concatenating location()
-
-            >>> reg = bloqade.start.add_positions([(0,0),(1,1),(2,2),(3,3)])
-            >>> loc = reg.rydberg.detuning.location(0)
-            >>> loc = loc.location(1).location(2)
 
         """
         return Location(self, label)
@@ -134,11 +140,27 @@ def __init__(self, parent: Builder, scale) -> None:
     def location(self, label: int):
         """
         - Append another location to the current location after scale the previous one
+
+        Args:
+            label (int): The label of the location
+
+        Examples:
+
+            - Append location 1 after scale location 0 by 1.2.
+
+            >>> reg = bloqade.start.add_positions([(0,0),(1,1),(2,2),(3,3)])
+            >>> loc = reg.rydberg.detuning.location(0).scale(1.2)
+            >>> loc = loc.location(1)
+
         - Possible Next <Location>:
 
             -> `...location(int).location(int)`
                 :: keep adding location into current list
 
+            -> `...location(int).scale(float)`
+                :: specify scaling factor to current location
+                for the preceeding waveform
+
         - Possible Next <WaveForm>:
 
             -> `...location(int).linear()`
@@ -163,16 +185,6 @@ def location(self, label: int):
                 :: apply callable as waveform.
 
 
-        Args:
-            label (int): The label of the location
-
-        Examples:
-
-            - Append location 1 after scale location 0 by 1.2.
-
-            >>> reg = bloqade.start.add_positions([(0,0),(1,1),(2,2),(3,3)])
-            >>> loc = reg.rydberg.detuning.location(0).scale(1.2)
-            >>> loc = loc.location(1)
 
         """
         return Location(self, label)

src/bloqade/builder/spatial.py

@@ -11,14 +11,37 @@ class SpatialModulation(Builder):
 
     def location(self, label: int):
         """
-        - Addressing one or multiple specific location(s) for preceeding waveform.
+        Addressing one or multiple specific location(s) for preceeding waveform.
+
+        (See [`Location`][bloqade.builder.location.Location] for more details])
+
+        Args:
+            label (int): The label of the location to apply the following waveform to.
+
+        Examples:
+
+            - Addressing rydberg detuning to location 1 on a system with 4 sites.
+
+            >>> reg = bloqade.start.add_positions([(0,0),(1,1),(2,2),(3,3)])
+            >>> loc = reg.rydberg.detuning.location(1)
+
+            - Addressing rydberg detuning on both location
+            0 and 2 on a system with 4 sites.
+
+            >>> reg = bloqade.start.add_positions([(0,0),(1,1),(2,2),(3,3)])
+            >>> loc = reg.rydberg.detuning.location(1).location(2)
+
+        Note:
+            label index start with 0, and should be positive.
+
         - Possible Next <Location>:
 
             -> `...location(int).location(int)`
                 :: adding location into current list
 
             -> `...location(int).scale(float)`
-                :: specify scaling factor for the preceeding waveform
+                :: specify scaling factor to current location
+                for the preceeding waveform
 
         - Possible Next <WaveForm>:
 
@@ -44,29 +67,6 @@ def location(self, label: int):
                 :: apply callable as waveform.
 
 
-        (See [`Location`][bloqade.builder.location.Location] for more details])
-
-        Args:
-            label (int): The label of the location to apply the following waveform to.
-
-        Examples:
-
-            - Addressing rydberg detuning to location 1 on a system with 4 sites.
-
-            >>> reg = bloqade.start.add_positions([(0,0),(1,1),(2,2),(3,3)])
-            >>> loc = reg.rydberg.detuning.location(1)
-
-            - Addressing rydberg detuning on both location
-            0 and 2 on a system with 4 sites.
-
-            >>> reg = bloqade.start.add_positions([(0,0),(1,1),(2,2),(3,3)])
-            >>> loc = reg.rydberg.detuning.location(1).location(2)
-
-
-        Note:
-            label index start with 0, and should be positive.
-
-
         """
         from .location import Location