API docstrings completed (#17)

* update version

* add pypi version number image

* Get badges working

* Change BenchMarkData to Benchmarkdata

* Improve docstrings

* Use Material for docstring style

* Add a temporary project-specific logo

* fix typo

* Make logo background transparent

* Add github stuff to docs

* tweaks to mkdocs config

* Polishing of documentation

* Complete all API docstrings

src/echosms/benchmarkdata.py

@@ -7,12 +7,12 @@
 class BenchmarkData:
     """Convenient interface to the benchmark dataset.
 
-    This dataset contains the TS values from Jech et al., 2015.
+    This dataset contains the TS results from Jech et al., 2015.
 
     Jech, J.M., Horne, J.K., Chu, D., Demer, D.A., Francis, D.T.I., Gorska, N., Jones, B.,
     Lavery, A.C., Stanton, T.K., Macaulay, G.J., Reeder, D.B., Sawada, K., 2015.
     Comparisons among ten models of acoustic backscattering used in aquatic ecosystem research.
-    Journal of the Acoustical Society of America 138, 3742–3764. https://doi.org/10.1121/1.4937607
+    Journal of the Acoustical Society of America 138, 3742–3764. <https://doi.org/10.1121/1.4937607>
     """
 
     def __init__(self):
@@ -26,11 +26,23 @@ def __init__(self):
         self.freq_data = pd.read_csv(freq_data_file)
 
     def dataset_angle(self):
-        """Return a Pandas dataframe containing the TS as a function of incidence angle dataset."""
+        """Provide the angle benchmark data.
+
+        Returns
+        -------
+        : Pandas DataFrame
+            The TS as a function of incidence angle.
+        """
         return self.angle_data
 
     def dataset_freq(self):
-        """Return a Pandas dataframe containing the TS as a function of frequency dataset."""
+        """Provide the frequency benchmark data.
+
+        Returns
+        -------
+        : Pandas DataFrame
+            The TS as a function of frequency.
+        """
         return self.freq_data
 
     # def dataset_angle(self, names):

src/echosms/dcmmodel.py

@@ -40,18 +40,18 @@ def calculate_ts_single(self, medium_c, medium_rho, a, b, theta, f, model_type,
         b : float
             Length of the cylinderical target [m].
         theta : float
-            Pitch angle(s) to calculate the scattering at [degrees]. An angle of 0 is head on,
+            Pitch angle(s) to calculate the scattering at [°]. An angle of 0 is head on,
             90 is dorsal, and 180 is tail on.
         f : float
             Frequencies to calculate the scattering at [Hz].
         model_type : str
-            The model type. Supported model types are given in the model_types class variable.
+            The model type. Supported model types are given in the model_types class attribute.
         target_c : float, optional
             Sound speed in the fluid inside the sphere [m/s].
-            Only required for `model_type` of ``fluid filled``
+            Only required for `model_type` of ``fluid filled``.
         target_rho : float, optional
             Density of the fluid inside the sphere [kg/m³].
-            Only required for `model_type` of ``fluid filled``
+            Only required for `model_type` of ``fluid filled``.
 
         Returns
         -------

src/echosms/mssmodel.py

@@ -42,18 +42,18 @@ def calculate_ts_single(self, medium_c, medium_rho, a, theta, f, model_type,
         a : float
             Radius of the spherical target [m].
         theta : float
-            Pitch angle(s) to calculate the scattering at [degrees]. An angle of 0 is head on,
+            Pitch angle(s) to calculate the scattering at [°]. An angle of 0 is head on,
             90 is dorsal, and 180 is tail on.
         f : float
             Frequencies to calculate the scattering at [Hz].
         model_type : str
             The model type. Supported model types are given in the model_types class variable.
         target_c : float, optional
             Sound speed in the fluid inside the sphere [m/s].
-            Only required for `model_type` of ``fluid filled``
+            Only required for `model_type` of ``fluid filled``.
         target_rho : float, optional
             Density of the fluid inside the sphere [kg/m³].
-            Only required for `model_type` of ``fluid filled``
+            Only required for `model_type` of ``fluid filled``.
         shell_c : float, optional
             Sound speed in the spherical shell [m/s].
             Only required for `model_type`s that include a fluid shell.

src/echosms/psmsmodel.py

@@ -34,19 +34,19 @@ def calculate_ts_single(self, medium_c, medium_rho, a, b, theta, f, model_type,
             Prolate spheroid major axis radius [m].
         b : float
             Prolate spheroid minor axis radius [m].
-        theta : float or array of float
-            Pitch angle(s) to calculate the scattering at [degrees]. An angle of 0 is head on,
+        theta : float
+            Pitch angle(s) to calculate the scattering at [°]. An angle of 0 is head on,
             90 is dorsal, and 180 is tail on.
-        f : float or array of float
+        f : float
             Frequencies to calculate the scattering at [Hz].
         model_type : str
             The model type. Supported model types are given in the model_types class variable.
         target_c : float, optional
             Sound speed in the fluid inside the target [m/s].
-            Only required for `model_type` of ``fluid filled``
+            Only required for `model_type` of ``fluid filled``.
         target_rho : float, optional
             Density of the fluid inside the target [kg/m³].
-            Only required for `model_type` of ``fluid filled``
+            Only required for `model_type` of ``fluid filled``.
 
         Returns
         -------

src/echosms/referencemodels.py

@@ -27,15 +27,38 @@ def __init__(self):
                     pass
 
     def models(self):
-        """Return the full set of model definitions."""
+        """Provide the full set of model definitions.
+
+        Returns
+        -------
+        : dict
+            The contents of the ```target definitions.toml`` file in the form of a dict.
+        """
         return self.defs
 
     def model_names(self):
-        """Return the names of all model definitions."""
+        """Names of all model definitions.
+
+        Returns
+        -------
+        : iterable of str
+            All model names in the ``target definitions/toml`` file.
+        """
         return [n['name'] for n in self.defs['target']]
 
     def get_model_specification(self, name):
-        """Get the model defintions for a particular model."""
+        """Get the model defintions for a particular model.
+
+        Parameters
+        ----------
+        name : str
+            The name of a model in the ``target definitions.toml`` file.
+
+        Returns
+        -------
+        : dict
+            The model definitions for the requested model or ``None`` if no model with that name.
+        """
         models = pd.DataFrame(self.defs['target'])
         m = models.query('name == @name')
         if len(m) == 1:
@@ -49,8 +72,23 @@ def get_model_parameters(self, name):
 
         Model parameters are a subset of the model specification where the non-numerical
         items have been removed.
+
+        Parameters
+        ----------
+        name : str
+            The name of a model in the ``target definitions.toml`` file.
+
+        Returns
+        -------
+        : dict
+            The model parameters for the requested model or ``None`` if no model with that name.
+
         """
         s = self.get_model_specification(name)
+
+        if s is None:
+            return s
+
         # Remove the entries that are not parameters
         p = s
         del p['name']