Fix more sphinx nitpick docs warnings

Mostly adding missing docstrings to classes or fixing syntax. The actual docstring content has not yet been properly updated and needs a refresh which will be done later.

Author: ptsOSL

src/atip/simulator.py

@@ -22,7 +22,9 @@ class LatticeData:
 
 
 def calculate_optics(
-    at_lattice: at.Lattice, refpts: ArrayLike, disable_emittance: bool = False
+    at_lattice: at.lattice_object.Lattice,
+    refpts: ArrayLike,
+    disable_emittance: bool = False,
 ) -> LatticeData:
     """Perform the physics calculations on the lattice.
 
@@ -33,7 +35,7 @@ def calculate_optics(
 
     Args:
         at_lattice (at.lattice_object.Lattice): AT lattice definition.
-        refpts (numpy.array): A boolean array specifying the points at which
+        refpts (numpy.typing.NDArray): A boolean array specifying the points at which
                                to calculate physics data.
         disable_emittance (bool): whether to calculate emittance.
 
@@ -79,7 +81,7 @@ class ATSimulator:
            _at_lat (at.lattice_object.Lattice): The centralised instance of an
                                                  AT lattice from which the
                                                  physics data is calculated.
-           _rp (numpy.array): A boolean array to be used as refpts for the
+           _rp (numpy.typing.NDArray): A boolean array to be used as refpts for the
                                physics calculations.
             _disable_emittance (bool): Whether or not to perform the beam
                                         envelope based emittance calculations.
@@ -388,7 +390,7 @@ def get_orbit(self, field=None):
                           if None return whole orbit vector.
 
         Returns:
-            numpy.array: The x, x phase, y or y phase for the AT lattice as an
+            numpy.typing.NDArray: The x, x phase, y or y phase for the AT lattice as an
             array of floats the length of the AT lattice.
 
         Raises:
@@ -417,7 +419,7 @@ def get_dispersion(self, field=None):
                           None return whole dispersion vector.
 
         Returns:
-            numpy.array: The eta x, eta prime x, eta y or eta prime y for the
+            numpy.typing.NDArray: The eta x, eta prime x, eta y or eta prime y for the
             AT lattice as an array of floats the length of the AT lattice.
 
         Raises:
@@ -441,31 +443,31 @@ def get_alpha(self):
         """Return the alpha vector at every element in the AT lattice.
 
         Returns:
-            numpy.array: The alpha vector for each element.
+            numpy.typing.NDArray: The alpha vector for each element.
         """
         return self._lattice_data.twiss["alpha"][:-1]
 
     def get_beta(self):
         """Return the beta vector at every element in the AT lattice.
 
         Returns:
-            numpy.array: The beta vector for each element.
+            numpy.typing.NDArray: The beta vector for each element.
         """
         return self._lattice_data.twiss["beta"][:-1]
 
     def get_mu(self):
         """Return mu at every element in the AT lattice.
 
         Returns:
-            numpy.array: The mu array for each element.
+            numpy.typing.NDArray: The mu array for each element.
         """
         return self._lattice_data.twiss["mu"][:-1]
 
     def get_m66(self):
         """Return the 6x6 transfer matrix for every element in the AT lattice.
 
         Returns:
-            numpy.array: The 6x6 transfer matrix for each element.
+            numpy.typing.NDArray: The 6x6 transfer matrix for each element.
         """
         return self._lattice_data.twiss["M"][:-1]
 
@@ -506,7 +508,7 @@ def get_radiation_integrals(self):
         """Return the 5 Synchrotron Integrals for the AT lattice.
 
         Returns:
-            numpy.array: The 5 radiation integrals.
+            numpy.typing.NDArray: The 5 radiation integrals.
         """
         return numpy.asarray(self._lattice_data.radint)
 
@@ -542,7 +544,7 @@ def get_damping_partition_numbers(self):
         """Return the damping partition numbers for the 3 normal modes.
 
         Returns:
-            numpy.array: The damping partition numbers of the AT lattice.
+            numpy.typing.NDArray: The damping partition numbers of the AT lattice.
         """
         _, I2, _, I4, _ = self._lattice_data.radint
         Jx = 1 - (I4 / I2)
@@ -558,7 +560,7 @@ def get_damping_times(self):
         Radiation; August 2013; eqn. 68
 
         Returns:
-            numpy.array: The damping times of the AT lattice.
+            numpy.typing.NDArray: The damping times of the AT lattice.
         """
         E0 = self.get_energy()
         U0 = self.get_energy_loss()

src/virtac/atip_ioc_entry.py

@@ -18,6 +18,7 @@
 
 
 def parse_arguments():
+    """Parse command line arguments sent to virtac"""
     parser = argparse.ArgumentParser()
     parser.add_argument("ring_mode", nargs="?", type=str, help="Ring mode name")
     parser.add_argument(
@@ -39,6 +40,7 @@ def parse_arguments():
 
 
 def main():
+    """Main entrypoint for virtac. Executed when running the 'virtac' command"""
     args = parse_arguments()
     log_level = logging.DEBUG if args.verbose else logging.INFO
     logging.basicConfig(level=log_level, format=LOG_FORMAT)

src/virtac/atip_server.py

@@ -541,7 +541,7 @@ def set_feedback_record(self, index, field, value):
             value (number): The value to be set.
 
         Raises:
-            pytac.exceptions.FieldException: If the lattice or element does
+            pytac.FieldException: If the lattice or element does
                                               not have the specified field.
         """
         try:

src/virtac/create_csv.py

@@ -13,7 +13,7 @@
 
 
 def generate_feedback_pvs(all_elements):
-    # Also get families for tune feedback
+    """Get feedback pvs. Also get families for tune feedback"""
     tune_quad_elements = set(
         all_elements.q1d
         + all_elements.q2d
@@ -54,8 +54,9 @@ def generate_feedback_pvs(all_elements):
 
 
 def generate_bba_pvs(all_elements):
-    # Data to be written is stored as a list of tuples each with structure:
-    #     element index (int), field (str), pv (str), value (int).
+    """Data to be written is stored as a list of tuples each with structure:
+    element index (int), field (str), pv (str), value (int).
+    """
     data = [("index", "field", "pv", "value", "read-only")]
     # Iterate over the BPMs to construct the PV names.
     for elem in all_elements.bpm:
@@ -76,6 +77,10 @@ def generate_bba_pvs(all_elements):
 def generate_pv_limits(lattice):
     """Get the control limits and precision values from the live machine for
     all normal PVS.
+
+    Args:
+        lattice (pytac.lattice.Lattice): The pytac lattice being used by the virtual
+        machine
     """
     data = [("pv", "upper", "lower", "precision")]
     for element in lattice:
@@ -271,6 +276,7 @@ def write_data_to_file(data, filename, ring_mode):
 
 
 def parse_arguments():
+    """The arguments passed to this script to configure how the csv is to be created"""
     parser = argparse.ArgumentParser(
         description="Generate CSV file to define the PVs served by the "
         "virtual accelerator IOC."