Fix some sphinx code docs references

Changes the names of various types so that Sphinx can add the correct link to the relevant docs. Such as changing the type callable to typing.Callable. There are many more to fix, but lots of them are due to missing docs to link to for pytac and pyAT

Author: ptsOSL

src/atip/load_sim.py

@@ -21,7 +21,7 @@ def load_from_filepath(
         pytac_lattice (pytac.lattice.Lattice): An instance of a Pytac lattice.
         at_lattice_filepath (str): The path to a .mat file from which the
                                     Accelerator Toolbox lattice can be loaded.
-        callback (callable): To be called after completion of each round of
+        callback (typing.Callable): To be called after completion of each round of
                               physics calculations.
         disable_emittance (bool): Whether the emittance should be calculated.
 
@@ -44,7 +44,7 @@ def load(pytac_lattice, at_lattice, callback=None, disable_emittance=False):
         pytac_lattice (pytac.lattice.Lattice): An instance of a Pytac lattice.
         at_lattice (at.lattice_object.Lattice): An instance of an Accelerator
                                               Toolbox lattice object.
-        callback (callable): To be called after completion of each round of
+        callback (typing.Callable): To be called after completion of each round of
                               physics calculations.
         disable_emittance (bool): Whether the emittance should be calculated.
 

src/atip/sim_data_sources.py

@@ -52,7 +52,7 @@ def __init__(self, at_element, index, atsim, fields=None):
                                                data source is attached to.
             index (int): The element's index in the ring, starting from 1.
             atsim (ATSimulator): An instance of an ATSimulator object.
-            fields (list, optional): The fields found on this element.
+            fields (list, typing.Optional): The fields found on this element.
 
         Raises:
             ValueError: if an unsupported field is passed, i.e. a field not in
@@ -111,7 +111,7 @@ def add_field(self, field):
                           this data_source.
 
         Raises:
-            FieldException: if the specified field is already present or if it
+            pytac.FieldException: if the specified field is already present or if it
                              is not supported.
         """
         if field in self._fields:
@@ -128,10 +128,10 @@ def get_value(self, field, handle=None, throw=True):
 
         Args:
             field (str): The requested field.
-            handle (str, optional): Handle is not needed and is only here to
+            handle (str, typing.Optional): Handle is not needed and is only here to
                                      conform with the structure of the
                                      DataSource base class.
-            throw (bool, optional): If the check for completion of outstanding
+            throw (bool, typing.Optional): If the check for completion of outstanding
                                      calculations times out, then:
                                      if True, raise a ControlSystemException;
                                      if False, log a warning and return the
@@ -141,8 +141,8 @@ def get_value(self, field, handle=None, throw=True):
             float: The value of the specified field on this data source.
 
         Raises:
-            FieldException: if the specified field does not exist.
-            ControlSystemException: if the calculation completion check fails,
+            pytac.FieldException: if the specified field does not exist.
+            pytac.ControlSystemException: if the calculation completion check fails,
                                      and throw is True.
         """
         # Wait for any outstanding calculations to conclude, to ensure they are
@@ -168,13 +168,13 @@ def set_value(self, field, value, throw=None):
         Args:
             field (str): The requested field.
             value (float): The value to be set.
-            throw (bool, optional): Throw is not needed and is only here to
+            throw (bool, typing.Optional): Throw is not needed and is only here to
                                      conform with the structure of the
                                      DataSource base class.
 
         Raises:
-            HandleException: if the specified field cannot be set to.
-            FieldException: if the specified field does not exist.
+            pytac.HandleException: if the specified field cannot be set to.
+            pytac.FieldException: if the specified field does not exist.
         """
         if field in self._fields:
             if field in self._set_field_funcs.keys():
@@ -418,10 +418,10 @@ def get_value(self, field, handle=None, throw=True):
 
         Args:
             field (str): The requested field.
-            handle (str, optional): Handle is not needed and is only here to
+            handle (str, typing.Optional): Handle is not needed and is only here to
                                      conform with the structure of the
                                      DataSource base class.
-            throw (bool, optional): If the check for completion of outstanding
+            throw (bool, typing.Optional): If the check for completion of outstanding
                                      calculations times out, then:
                                      if True, raise a ControlSystemException;
                                      if False, log a warning and return the
@@ -431,8 +431,8 @@ def get_value(self, field, handle=None, throw=True):
             float: The value of the specified field on this data source.
 
         Raises:
-            FieldException: if the specified field does not exist.
-            ControlSystemException: if the calculation completion check fails,
+            pytac.FieldException: if the specified field does not exist.
+            pytac.ControlSystemException: if the calculation completion check fails,
                                      and throw is True.
         """
         # Wait for any outstanding calculations to conclude, to ensure they are
@@ -469,12 +469,12 @@ def set_value(self, field, value, throw=None):
         Args:
             field (str): The requested field.
             value (float): The value to be set.
-            throw (bool, optional): Throw is not needed and is only here to
+            throw (bool, typing.Optional): Throw is not needed and is only here to
                                      conform with the structure of the
                                      DataSource base class.
 
         Raises:
-            HandleException: as setting values to Pytac lattice fields is not
+            pytac.HandleException: as setting values to Pytac lattice fields is not
                               currently supported.
         """
         raise HandleException(

src/atip/simulator.py

@@ -107,7 +107,7 @@ def __init__(self, at_lattice, callback=None, disable_emittance=False):
         Args:
             at_lattice (at.lattice_object.Lattice): An instance of an AT
                                                      lattice object.
-            callback (callable): Optional, if passed it is called on completion
+            callback (typing.Callable): Optional, if passed it is called on completion
                                   of each round of physics calculations.
             disable_emittance (bool): Whether or not to perform the beam
                                        envelope based emittance calculations.
@@ -142,7 +142,7 @@ def queue_set(self, func, field, value):
         """Add a change to the queue, to be applied when the queue is emptied.
 
         Args:
-            func (callable): The function to be called to apply the change.
+            func (typing.Callable): The function to be called to apply the change.
             field (str): The field to be changed.
             value (float): The value to be set.
         """
@@ -178,7 +178,7 @@ def _recalculate_phys_data(self, callback):
            thread to warnings.
 
         Args:
-            callback (callable): to be called after each round of calculations,
+            callback (typing.Callable): to be called after each round of calculations,
                                   indicating that they have concluded.
 
         Warns:
@@ -254,7 +254,7 @@ def wait_for_calculations(self, timeout=10):
         changes to the AT lattice, i.e. the physics data is fully up to date.
 
         Args:
-            timeout (float, optional): The number of seconds to wait for.
+            timeout (float, typing.Optional): The number of seconds to wait for.
 
         Returns:
             bool: False if the timeout elapsed before the calculations
@@ -342,7 +342,7 @@ def get_tune(self, field=None):
             float: The x or y tune for the AT lattice.
 
         Raises:
-            FieldException: if the specified field is not valid for tune.
+            pytac.FieldException: if the specified field is not valid for tune.
         """
         tunes = self._lattice_data.tunes
         if field is None:
@@ -365,7 +365,7 @@ def get_chromaticity(self, field=None):
             float: The x or y chromaticity for the AT lattice.
 
         Raises:
-            FieldException: if the specified field is not valid for
+            pytac.FieldException: if the specified field is not valid for
                              chromaticity.
         """
         chrom = self._lattice_data.chrom
@@ -392,7 +392,7 @@ def get_orbit(self, field=None):
             array of floats the length of the AT lattice.
 
         Raises:
-            FieldException: if the specified field is not valid for orbit.
+            pytac.FieldException: if the specified field is not valid for orbit.
         """
         closed_orbit = self._lattice_data.twiss["closed_orbit"]
         if field is None:
@@ -421,7 +421,7 @@ def get_dispersion(self, field=None):
             AT lattice as an array of floats the length of the AT lattice.
 
         Raises:
-            FieldException: if the specified field is not valid for dispersion.
+            pytac.FieldException: if the specified field is not valid for dispersion.
         """
         dispersion = self._lattice_data.twiss["dispersion"]
         if field is None:
@@ -485,7 +485,7 @@ def get_emittance(self, field=None):
             float: The x or y emittance for the AT lattice.
 
         Raises:
-            FieldException: if the specified field is not valid for emittance.
+            pytac.FieldException: if the specified field is not valid for emittance.
         """
         if not self._disable_emittance:
             if field is None:

src/atip/utils.py

@@ -38,7 +38,7 @@ def loader(mode="I04", callback=None, disable_emittance=False):
 
     Args:
         mode (str): The lattice operation mode.
-        callback (callable): Callable to be called after completion of each
+        callback (typing.Callable): Callable to be called after completion of each
                               round of physics calculations in ATSimulator.
         disable_emittance (bool): Whether the emittance should be calculated.
 
@@ -67,7 +67,7 @@ def preload_at(at_lat):
                                       the elements.
 
     returns:
-        obj: The elems object with the elements loaded onto it by type.
+        obj (class): The elems object with the elements loaded onto it by type.
     """
 
     class elems:
@@ -114,7 +114,7 @@ def preload(pytac_lat):
                                             to get the elements.
 
     returns:
-        obj: The elems object with the elements loaded onto it by family.
+        obj(class): The elems object with the elements loaded onto it by family.
     """
 
     class elems:

src/virtac/atip_server.py

@@ -66,17 +66,17 @@ def __init__(
     ):
         """
         Args:
-            ring_mode (string): The ring mode to create the lattice in.
-            limits_csv (string): The filepath to the .csv file from which to
+            ring_mode (str): The ring mode to create the lattice in.
+            limits_csv (str): The filepath to the .csv file from which to
                                     load the pv limits, for more information
                                     see create_csv.py.
-            feedback_csv (string): The filepath to the .csv file from which to
+            feedback_csv (str): The filepath to the .csv file from which to
                                     load the feedback records, for more
                                     information see create_csv.py.
-            mirror_csv (string): The filepath to the .csv file from which to
+            mirror_csv (str): The filepath to the .csv file from which to
                                   load the mirror records, for more information
                                   see create_csv.py.
-            tune_csv (string): The filepath to the .csv file from which to
+            tune_csv (str): The filepath to the .csv file from which to
                                 load the tune feedback records, for more
                                 information see create_csv.py.
             disable_emittance (bool): Whether the emittance should be disabled.
@@ -149,7 +149,7 @@ def _create_records(self, limits_csv, disable_emittance):
                need to be created for them.
 
         Args:
-            limits_csv (string): The filepath to the .csv file from which to
+            limits_csv (str): The filepath to the .csv file from which to
                                     load the pv limits.
             disable_emittance (bool): Whether the emittance related PVs should be
                                         created or not.
@@ -297,7 +297,7 @@ def _create_feedback_records(self, feedback_csv, disable_emittance):
         cases are also created.
 
         Args:
-            feedback_csv (string): The filepath to the .csv file to load the
+            feedback_csv (str): The filepath to the .csv file to load the
                                     records in accordance with.
             disable_emittance (bool): Whether the emittance related PVs should be
                                         created or not.
@@ -374,7 +374,7 @@ def _create_mirror_records(self, mirror_csv):
         passed, see create_csv.py for more information.
 
         Args:
-            mirror_csv (string): The filepath to the .csv file to load the
+            mirror_csv (str): The filepath to the .csv file to load the
                                     records in accordance with.
         """
         csv_reader = csv.DictReader(open(mirror_csv))
@@ -537,7 +537,7 @@ def set_feedback_record(self, index, field, value):
         Args:
             index (int): The index of the element on which to set the value;
                           starting from 1, 0 is used to set on the lattice.
-            field (string): The field to set the value to.
+            field (str): The field to set the value to.
             value (number): The value to be set.
 
         Raises:

src/virtac/create_csv.py

@@ -99,13 +99,17 @@ def generate_pv_limits(lattice):
 
 def generate_mirrored_pvs(lattice):
     """Structure of data:
-    output type: The type of output record to create, only 'aIn', 'longIn',
+
+    output type:
+        The type of output record to create, only 'aIn', 'longIn',
         'Waveform' types are currently supported; if '' then output to an
         existing in record already created in ATIPServer, 'caput' is also a
         special case it creates a mask for cothread.catools.caput calling
         set(value) on this mask will call caput with the output PV and the
         passed value.
-    mirror type: The type of mirroring to apply:
+
+    mirror type (The type of mirroring to apply):
+
         - basic: set the value of the input record to the output record.
         - summate: sum the values of the input records and set the result to
             the output record.
@@ -114,12 +118,18 @@ def generate_mirrored_pvs(lattice):
             of the input record and set the result to the output record. N.B.
             the only transformation type currently supported is 'inverse'.
         - refresh: monitor the in PV and on a change call refresh_record on
-                   the output PV.
-    in: The PV(s) to be monitored, on change mirror is updated, if multiple
+            the output PV.
+
+    in:
+        The PV(s) to be monitored, on change mirror is updated, if multiple
         then the PVs should be separated by a comma and one space.
-    out: The single PV to output to, if a 'record type' is spcified then a new
+
+    out:
+        The single PV to output to, if a 'record type' is spcified then a new
         record will be created and so must not exist already.
-    value: The inital value of the output record.
+
+    value:
+        The inital value of the output record.
     """
     data = [("output type", "mirror type", "in", "out", "value")]
     # Tune PV aliases.

src/virtac/mirror_objects.py

@@ -64,7 +64,7 @@ class transform:
     def __init__(self, transformation, output_record):
         """
         Args:
-            transformation (callable): The transformation to be applied.
+            transformation (typing.Callable): The transformation to be applied.
             output_record (pythonSoftIoc.RecordWrapper): The record to set the
                                                           transformed value to.
         """