Polishing of the documentation and formatting (#15)

* 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

.github/workflows/build-docs.yml

@@ -14,6 +14,6 @@ jobs:
       - uses: actions/setup-python@v5
         with:
           python-version: 3.x
-      - run: pip install mkdocs mkdocs mkdocstrings[python]
+      - run: pip install mkdocs mkdocstrings[python] mkdocs-material
       - run: mkdocs gh-deploy --force --clean --verbose
 

docs/api_reference.md

@@ -24,9 +24,8 @@ Additional reference models may be defined in the future and can be added to the
 
 ::: echosms.ReferenceModels
 
-
-## BenchMarkData
-::: echosms.BenchMarkData
+## BenchmarkData
+::: echosms.BenchmarkData
 
 
 ## Utilities

mkdocs.yml

@@ -6,7 +6,19 @@ nav:
     - Benchmarks: benchmark_data.md
     - API Reference: api_reference.md
 
-theme: readthedocs 
+theme: 
+    name: material 
+    logo: echoSMs_logo.png
+    favicon: echoSMs_logo.png
+    icon:
+        repo: fontawesome/brands/github
+    features:
+        - navigation.top
+        - toc.integrate
+        - content.action.view
+
+repo_url: https://github.com/ices-tools-dev/echoSMs
+edit_uri: edit/main/docs/
 
 plugins:
     - search
@@ -22,5 +34,7 @@ plugins:
                     inherited_members: true
                     show_root_heading: false
                     show_root_toc_entry: false
-                    show_source: false
+                    show_source: true
                     heading_level: 3
+                    filters:
+                    - "!^_"

src/echosms/__init__.py

@@ -1,11 +1,11 @@
 """Setup the public API for echoSMs."""
 from .utils import k, eta, h1, df_from_dict, da_from_dict
 from .scattermodelbase import ScatterModelBase
-from .benchmarkdata import BenchMarkData
+from .benchmarkdata import BenchmarkData
 from .referencemodels import ReferenceModels
 from .mssmodel import MSSModel
 from .psmsmodel import PSMSModel
 from .dcmmodel import DCMModel
 
-__all__ = ['ScatterModelBase', 'BenchMarkData', 'ReferenceModels', 'MSSModel', 'PSMSModel',
+__all__ = ['ScatterModelBase', 'BenchmarkData', 'ReferenceModels', 'MSSModel', 'PSMSModel',
            'DCMModel', 'k', 'eta', 'h1', 'da_from_dict', 'df_from_dict']

src/echosms/benchmarkdata.py

@@ -4,7 +4,7 @@
 import pandas as pd
 
 
-class BenchMarkData:
+class BenchmarkData:
     """Convenient interface to the benchmark dataset.
 
     This dataset contains the TS values from Jech et al., 2015.

src/echosms/dcmmodel.py

@@ -55,7 +55,8 @@ def calculate_ts_single(self, medium_c, medium_rho, a, b, theta, f, model_type,
 
         Returns
         -------
-        ts : the target strength (re 1 m²) of the target [dB].
+        : float
+            The target strength (re 1 m²) of the target [dB].
 
         Notes
         -----

src/echosms/mssmodel.py

@@ -12,8 +12,8 @@
 class MSSModel(ScatterModelBase):
     """Modal series solution (MSS) scattering model.
 
-    This class contains methods to calculate acoustic scatter from spheres and shells with various
-    boundary conditions.
+    This class calculates acoustic scatter from spheres and shells with various
+    boundary conditions, as listed in the ``model_types`` class attribute.
     """
 
     def __init__(self):
@@ -67,7 +67,7 @@ def calculate_ts_single(self, medium_c, medium_rho, a, theta, f, model_type,
 
         Returns
         -------
-        :
+        : float
             The target strength (re 1 m²) of the target [dB].
 
         Notes

src/echosms/psmsmodel.py

@@ -50,7 +50,8 @@ def calculate_ts_single(self, medium_c, medium_rho, a, b, theta, f, model_type,
 
         Returns
         -------
-        ts : the target strength (re 1 m²) of the target [dB].
+        : float
+            The target strength (re 1 m²) of the target [dB].
 
         Notes
         -----

src/echosms/scattermodelbase.py

@@ -11,16 +11,24 @@ class ScatterModelBase(abc.ABC):
     """Base class for a class that provides a scattering model.
 
     All scattering models should inherit from this class, have a name that
-    ends with 'Model', and provide __init__() and calculate_ts_single() functions.
+    ends with 'Model', and provide initialisation and calculate_ts_single() functions.
 
     Attributes
     ----------
-    long_name : string
-    short_name : string
-    analytical_type : string
-    model_types :
-    shapes :
-    max_ka :
+    long_name : str
+        The long name of the model.
+    short_name : str
+        A short version of the model's long name, typically an ancronym.
+    analytical_type : str
+        Whether the model implements an ``exact`` or an ``approximate`` model.
+    model_types : list of str
+        The types of boundary conditions that the model provides.
+    shapes : list of str
+        The shapes that the model can represent.
+    max_ka : float
+        An approximate maximum ka value that will result in accurate target strength results. Note
+        that ka is often not the only parameter that determines the accuracy of the model (e.g.,
+        aspect ratio and incident angle can also affect the accuracy).
 
     """
 

src/echosms/utils.py

@@ -84,8 +84,8 @@ def k(c: float, f: float) -> float:
 
     Returns
     -------
-    k : scalar or array_like
-        The acoustic wavenumber [m$^{-1}$].
+    :
+        The acoustic wavenumber [m⁻¹].
     """
     return 2*np.pi*f/c
 
@@ -96,7 +96,7 @@ def h1(n: int, z: float, derivative=False) -> complex:
     Parameters
     ----------
     n :
-        Order (n >= 0).
+        Order (n ≥ 0).
     z :
         Argument of the Hankel function.
     derivative :
@@ -107,6 +107,11 @@ def h1(n: int, z: float, derivative=False) -> complex:
     :
         Value of the spherical Hankel function
 
+    Raises
+    ------
+    ValueError
+        For negative n values.
+
     Notes
     -----
     The value of the Hankel function is calculated from spherical Bessel functions [1].

src/example_code.py

@@ -4,7 +4,7 @@
 import numpy as np
 
 from echosms import MSSModel, PSMSModel, DCMModel
-from echosms import BenchMarkData
+from echosms import BenchmarkData
 from echosms import ReferenceModels
 from echosms import df_from_dict, da_from_dict
 
@@ -15,7 +15,7 @@
     print('\t' + n)
 
 # Load the benchmark data (from Jech et al., 2015)
-bm = BenchMarkData()
+bm = BenchmarkData()
 bmf = bm.dataset_freq()
 bm_theta = bm.dataset_angle()