Merge pull request #99 from easyScience/98-prettify-the-autogenerated…

…-api-documention

98 prettify the autogenerated api documention

AUTHORS.rst

@@ -7,4 +7,5 @@ Contributors
 
 * Andrew R. McCluskey <andrew.mccluskey@ess.eu>
 * Andrew Sazonov <andrew.sazonov@ess.eu>
-* Simon Ward <simon.ward@ess.eu>
+* Simon Ward <simon.ward@ess.eu>
+* Andreas Pedersen <andreas.pedersen@ess.eu>

EasyReflectometry/calculators/calculator_base.py

@@ -27,16 +27,11 @@ class CalculatorBase(ComponentSerializer, metaclass=ABCMeta):
     _item_link: dict[str, str]
     _model_link: dict[str, str]
 
-    def __init_subclass__(cls, is_abstract: bool = False, **kwargs):
-        """
-        Initialise all subclasses so that they can be created in the factory
+    def __init_subclass__(cls, is_abstract: bool = False, **kwargs) -> None:
+        r"""Initialise all subclasses so that they can be created in the factory
 
         :param is_abstract: Is this a subclass which shouldn't be dded
-        :type is_abstract: bool
         :param kwargs: key word arguments
-        :type kwargs: dict
-        :return: None
-        :rtype: noneType
         """
         super().__init_subclass__(**kwargs)
         if not is_abstract:
@@ -47,17 +42,13 @@ def __init__(self):
         self._wrapper: WrapperBase
 
     def reset_storage(self) -> None:
-        """
-        Reset the storage area of the calculator
-        """
+        """Reset the storage area of the calculator"""
         self._wrapper.reset_storage()
 
     def create(self, model: Material | Layer | Multilayer | Model) -> list[ItemContainer]:
-        """
-        Creation function
+        """Creation function
 
         :param model: Object to be created
-        :return: Item containers of the objects
         """
         r_list = []
         t_ = type(model)
@@ -127,57 +118,50 @@ def create(self, model: Material | Layer | Multilayer | Model) -> list[ItemConta
         return r_list
 
     def assign_material_to_layer(self, material_id: str, layer_id: str) -> None:
-        """
-        Assign a material to a layer.
+        """Assign a material to a layer.
 
         :param material_id: The material name
         :param layer_id: The layer name
         """
         self._wrapper.assign_material_to_layer(material_id, layer_id)
 
     def add_layer_to_item(self, layer_id: str, item_id: str) -> None:
-        """
-        Add a layer to the item stack
+        """Add a layer to the item stack
 
         :param item_id: The item id
         :param layer_id: The layer id
         """
         self._wrapper.add_layer_to_item(layer_id, item_id)
 
     def remove_layer_from_item(self, layer_id: str, item_id: str) -> None:
-        """
-        Remove a layer from an item stack
+        """Remove a layer from an item stack
 
         :param item_id: The item id
         :param layer_id: The layer id
         """
         self._wrapper.remove_layer_from_item(layer_id, item_id)
 
     def add_item_to_model(self, item_id: str, model_id: str) -> None:
-        """
-        Add a layer to the item stack
+        """Add a layer to the item stack
 
         :param item_id: The item id
         :param model_id: The model id
         """
         self._wrapper.add_item(item_id, model_id)
 
     def remove_item_from_model(self, item_id: str, model_id: str) -> None:
-        """
-        Remove an item from the model
+        """Remove an item from the model
 
         :param item_id: The item id
         :param model_id: The model id
         """
         self._wrapper.remove_item(item_id, model_id)
 
     def fit_func(self, x_array: np.ndarray, model_id: str) -> np.ndarray:
-        """
-        Function to perform a fit
+        """Function to perform a fit.
 
         :param x_array: points to be calculated at
         :param model_id: The model id
-        :return: calculated points
         """
         return self._wrapper.calculate(x_array, model_id)
 

EasyReflectometry/calculators/wrapper_base.py

@@ -5,6 +5,7 @@
 
 class WrapperBase:
     def __init__(self):
+        """Constructor."""
         self.storage = {
             'material': {},
             'layer': {},
@@ -13,9 +14,7 @@ def __init__(self):
         }
 
     def reset_storage(self):
-        """
-        Reset the storage area to blank.
-        """
+        """Reset the storage area to blank."""
         self.storage = {
             'material': {},
             'layer': {},
@@ -25,64 +24,58 @@ def reset_storage(self):
 
     @abstractmethod
     def create_material(self, name: str):
-        """
-        Create a material using SLD.
+        """Create a material using SLD.
 
         :param name: The name of the material
         """
         ...
 
     @abstractmethod
     def create_layer(self, name: str):
-        """
-        Create a layer using Slab.
+        """Create a layer using Slab.
 
         :param name: The name of the layer
         """
         ...
 
     @abstractmethod
     def create_item(self, name: str):
-        """
-        Create an item using Stack.
+        """Create an item using Stack.
 
         :param name: The name of the item
         """
         ...
 
     @abstractmethod
     def create_model(self, name: str):
-        """
-        Create a model for analysis
+        """Create a model for analysis
 
         :param name: Name for the model
         """
         ...
 
     @abstractmethod
     def update_model(self, name: str, **kwargs):
-        """
-        Update the non-structural parameters of the model
+        """Update the non-structural parameters of the model
 
         :param name: Name for the model
+        :param kwargs:
+
         """
         ...
 
     @abstractmethod
     def get_model_value(self, name: str, key: str) -> float:
-        """
-        A function to get a given model value
+        """A function to get a given model value
 
         :param name: Name for the model
         :param key: The given value keys
-        :return: The desired value
         """
         ...
 
     @abstractmethod
     def assign_material_to_layer(self, material_name: str, layer_name: str):
-        """
-        Assign a material to a layer.
+        """Assign a material to a layer.
 
         :param material_name: The material name
         :param layer_name: The layer name
@@ -91,8 +84,7 @@ def assign_material_to_layer(self, material_name: str, layer_name: str):
 
     @abstractmethod
     def add_layer_to_item(self, layer_name: str, item_name: str):
-        """
-        Create a layer from the material of the same name, in a given item.
+        """Create a layer from the material of the same name, in a given item.
 
         :param layer_name: The layer name
         :param item_name: The item name
@@ -101,8 +93,7 @@ def add_layer_to_item(self, layer_name: str, item_name: str):
 
     @abstractmethod
     def add_item(self, item_name: str, model_name: str):
-        """
-        Add an item to the model.
+        """Add an item to the model.
 
         :param item_name: items to add to model
         :param model_name: Name for the model
@@ -111,8 +102,7 @@ def add_item(self, item_name: str, model_name: str):
 
     @abstractmethod
     def remove_layer_from_item(self, layer_name: str, item_name: str):
-        """
-        Remove a layer in a given item.
+        """Remove a layer in a given item.
 
         :param layer_name: The layer name
         :param item_name: The item name
@@ -121,8 +111,7 @@ def remove_layer_from_item(self, layer_name: str, item_name: str):
 
     @abstractmethod
     def remove_item(self, item_name: str, model_name: str):
-        """
-        Remove a given item.
+        """Remove a given item.
 
         :param item_name: The item name
         :param model_name: Name of the model
@@ -131,28 +120,24 @@ def remove_item(self, item_name: str, model_name: str):
 
     @abstractmethod
     def calculate(self, x_array: np.ndarray, model_name: str) -> np.ndarray:
-        """
-        For a given x calculate the corresponding y.
+        """For a given x calculate the corresponding y.
 
         :param x_array: array of data points to be calculated
         :param model_name: Name for the model
-        :return: points calculated at `x`
         """
         ...
 
     @abstractmethod
     def sld_profile(self, model_name: str) -> tuple[np.ndarray, np.ndarray]:
-        """
-        Return the scattering length density profile.
+        """Return the scattering length density profile.
 
         :param model_name: Name for the model
         :return: z and sld(z)
         """
         ...
 
     def update_material(self, name: str, **kwargs):
-        """
-        Update a material.
+        """Update a material.
 
         :param name: The name of the material
         """
@@ -162,8 +147,7 @@ def update_material(self, name: str, **kwargs):
             setattr(item, 'value', kwargs[key])
 
     def get_material_value(self, name: str, key: str) -> float:
-        """
-        A function to get a given material value
+        """A function to get a given material value
 
         :param name: The material name
         :param key: The given value keys
@@ -174,31 +158,28 @@ def get_material_value(self, name: str, key: str) -> float:
         return getattr(item, 'value')
 
     def update_layer(self, name: str, **kwargs):
-        """
-        Update a layer in a given item.
+        """Update a layer in a given item.
 
-        :param name: The layer name
+        :param name: The layer name.
+        :param kwargs:
         """
         layer = self.storage['layer'][name]
         for key in kwargs.keys():
             ii = getattr(layer, key)
             setattr(ii, 'value', kwargs[key])
 
     def get_layer_value(self, name: str, key: str) -> float:
-        """
-        A function to get a given layer value
+        """A function to get a given layer value
 
         :param name: The layer name
         :param key: The given value keys
-        :return: The desired value
         """
         layer = self.storage['layer'][name]
         ii = getattr(layer, key)
         return getattr(ii, 'value')
 
     def update_item(self, name: str, **kwargs):
-        """
-        Update a layer.
+        """Update a layer.
 
         :param name: The item name
         """
@@ -208,8 +189,7 @@ def update_item(self, name: str, **kwargs):
             setattr(ii, 'value', kwargs[key])
 
     def get_item_value(self, name: str, key: str) -> float:
-        """
-        A function to get a given item value
+        """A function to get a given item value
 
         :param name: The item name
         :param key: The given value keys

EasyReflectometry/data.py

@@ -10,12 +10,9 @@
 
 
 def load(fname: Union[TextIO, str]) -> sc.DataGroup:
-    """
-    Load data from an ORSO .ort file.
+    """Load data from an ORSO .ort file.
 
     :param fname: The file to be read.
-
-    :return: A scipp DataGroup for the loaded datasets.
     """
     try:
         return _load_orso(fname)
@@ -24,12 +21,9 @@ def load(fname: Union[TextIO, str]) -> sc.DataGroup:
 
 
 def _load_orso(fname: Union[TextIO, str]) -> sc.DataGroup:
-    """
-    Load from an ORSO compatible file.
+    """Load from an ORSO compatible file.
 
     :param fname: The path for the file to be read.
-
-    :return: A populated scipp DataGroup.
     """
     data = {}
     coords = {}
@@ -63,19 +57,12 @@ def _load_orso(fname: Union[TextIO, str]) -> sc.DataGroup:
 
 
 def _load_txt(fname: Union[TextIO, str]) -> sc.DataGroup:
-    """
-    Load data from a simple txt file.
+    """Load data from a simple txt file.
 
     :param fname: The path for the file to be read.
-
-    :return: A populated scipp DataGroup.
     """
     f_data = np.loadtxt(fname)
-    data = {
-        'R_0': sc.array(
-            dims=['Qz_0'], values=f_data[:, 1], variances=np.square(f_data[:, 2])
-        )
-    }
+    data = {'R_0': sc.array(dims=['Qz_0'], values=f_data[:, 1], variances=np.square(f_data[:, 2]))}
     coords = {
         data['R_0'].dims[0]: sc.array(
             dims=['Qz_0'],