From b72ad9dc718f100c6ab34d3741164e41769ee324 Mon Sep 17 00:00:00 2001
From: Gavin Macaulay <gavin@macaulay.co.nz>
Date: Fri, 16 Aug 2024 15:27:19 +1200
Subject: [PATCH] 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 |   2 +-
 docs/api_reference.md            |   5 ++---
 docs/echoSMs_logo.png            | Bin 0 -> 2993 bytes
 mkdocs.yml                       |  18 ++++++++++++++++--
 src/echosms/__init__.py          |   4 ++--
 src/echosms/benchmarkdata.py     |   2 +-
 src/echosms/dcmmodel.py          |   3 ++-
 src/echosms/mssmodel.py          |   6 +++---
 src/echosms/psmsmodel.py         |   3 ++-
 src/echosms/scattermodelbase.py  |  22 +++++++++++++++-------
 src/echosms/utils.py             |  11 ++++++++---
 src/example_code.py              |   4 ++--
 12 files changed, 54 insertions(+), 26 deletions(-)
 create mode 100644 docs/echoSMs_logo.png

diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml
index c0795e4..99b3363 100644
--- a/.github/workflows/build-docs.yml
+++ b/.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
       
diff --git a/docs/api_reference.md b/docs/api_reference.md
index 0530634..12aff33 100644
--- a/docs/api_reference.md
+++ b/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
diff --git a/docs/echoSMs_logo.png b/docs/echoSMs_logo.png
new file mode 100644
index 0000000000000000000000000000000000000000..edc0ecd2bdfecae5f670ee7629fb30fd76eb4020
GIT binary patch
literal 2993
zcmd^><yRC66UJ9UN>C&u1px^~N<tczu7%6O0@A|LA+fZ=lCs2Jx?$;VWI;g|mToEO
z?(PO(?%(mwInVsgoS82(=lL+<S|BA-Vme{~06?muEU*1Q$p`Tf;y&aAmO%UmJaW@k
z0s<-q8MYn@JZo7ESpc9KNpfrc(8Sr)QrA(KoSf|G>AAhV?d|PdT3YJp=%}x+KRrEd
zXlOV%IKX1D8yg$#?d^+;i+z24va+%yBqYARzHi>VdHVEeWo2bXMg|cP5j8dS_4Rd4
zP0i!Sj|Bw<7Zw(*tgHwL3B$s|LPJAMO-<|S>aMP?sHmtsJUq~7G#MEgH#avDiIkI*
zGcYhvQBj$lon>cdCnhF-{ra`OzW&_Y+{ML3R8$l#Ev>Ds?fUxq+S;0pjST?-0UaG(
zbab??uI{5pk2pCw{r&wvefl&tHI<c>g@=dt?Af#5zkfe0dv|x|=H`ZvkB@_cLrzZK
z-`}sKq%=N0J~%k|<Hrw1Mn+av*6!}^@bGXT5V*X&Tv}QxBqTICI_l@==k4unX=(ZE
z*RS{Q-<Ow{OG!zgP^giS5f&B}CMKpAFJ4ScO!)Zt(9qCqZEdBdrmCx}pPik(eED)^
zWyRCeb9Hr<fq~)ApFb%nDWs&Nl$4ah!oqQJaeI4vM@L6RMMamFm&3!u=jZ1$Gc!Cq
zJcoyeU0q%B^77l;+nbx4t*x!NxVX;F&V_}APo6w!Y;2T}kg&6}+uhv_3JQAu{Q1z(
z5IsG;mX_A%&!5fA%-Go2K79CKVq(I}%iG-CJTNejpPwHb94sRvGd4CB7#OImtel;l
z9UmWme}4~y!R+nr=jZ3m&CMw&C~j_UBqb$({`~3U;!<2(EGjDc_U&6QFR%Um{p#v!
z5fKq5C#UJ@>5`HXZEbB;RaGz;42Q!J2m~`T^YQVqhK7c#tE--#UPwrYk&)5&@81m#
z4Y|0uFc?frOG{Ex(#grm&d!dere<4Pn~si-f`UR$PEJ`_nYFcbK|z6|qhmrs0t5ny
ziHZ68^=m*tfV;bUW@ct`a<ZbLA`}WuPft%vOS7=B0D(ZUv9ZR+#$UdCQBzY(OiUCL
z6YK2kjEszQaB!%osCf12RbE~mA0J;+Q<Jo`w19vB2M33^xHvyQe^pi0gCA%RqOA|O
zbk_!f|NeglfOD{3<lzQHpOp>V001(~e|ls$5l#dE5P($VWp$L*@)Lb!z`6_%b~MZ8
z$0N5IB*vp~=UO~u(Ub3N+~rYGCiTl^2{fy7=lt-PvkI6C56LNLmRDe9rDXcY&fpu>
zRrfB`z!rM`_4a<x^JVVeom-bd>y7yXQSp{PjdYjN8n|>!<z_U?Bz$AYSpNXBI!`?9
zCkzGn#sSg_E!hC<L7sftgi<b?`AgL$5i1a=6dFaWgy4((WgqFnozXPog><T0GRf;M
zs&e_wzp};Vc(KK?IA0yw5Ps`<$~JlzSEz;1RE`W!wJS&#)S!!zkjz|erxdkP6nt$&
ztZiMe)cC!2<Q=U8J8QqpG7TK5z>5TPa-~4V&jD${Q$4X#5x;}N-6-*gq8vdUgK{4%
z2WY4yMJ(t2+QTedPuSH+hFN-n*qjbE;IYf=h5SS)`9G|QD<@&ZkYUosfjHv)1b{+E
zDL_@33$vY%jE4(=zfxj&kpEyV`1|Mrz8@<CPB;lN-8@)oiw-BNj$!AKpM5~kX4~~c
zgrN8*D8fQ6wzfA!-#AW!t=xlEQnk(&tYCa+tQ=%#^I2``RLB9@7h7e2>D6<M*A*2N
zyNh+HooNUeMbTxlakU+2gsgIbY{WHdG5C4;v2h-6y;Db9wyn#`xmoxm%C?2K-5lg1
zovK9~JSoUIVhl%S+7*NB++=b+I~c+FgrIxzbxFujwL^*&#KvQv*f%jwi(_w|Frxb<
zVtoTueB>>B(-y%?DzpdvfTo+q_Hypcw7e162f%hvKF!+%q!9OKm|%v}C>Tv_Bg`Z0
zZ!4|)iQE=B%3jtKr-@rguF&_LLgjS=4t{(p_VQ0^Pbt6{KW$jFvd1d`Bm|gifX0%+
z@K)5ti|J9hP_8(lGjczC;nHL|&w6tmJ9H8g{-$VXr`tM1*M7T-(WTb)&ZP|n%qW~H
zx34rBX(@LAIpxpIJoQT@tivxo3wRZ^N7|P*zfmetxQQ977`2{ULFe%}a;FtnNs&5d
zLD%QajUMlSxmx?F%PZp7-;_yRk`0KRJAJ$o6vKR3jkW@w;4|A0HI3IGN7`5KwBDy_
z{8AJAvZ@dokyBD_y)88=Di)9>cC4;WfUWLC1cm8=x0$MMnqI**6t@d2bw%DARXSrb
zi#^u`G_fx|?b>`JQOKshvf^FvBc-PiUXo2`SQRYofQ#wFknE~b+)WMy?}QSY{}G}I
z;IW>8^>a69$$BwzkY0T|r^MwMeK}{-e0;<Z4b3basu^zM6JHe3<MtPm{EH8wTBX=c
zxdyY;v<aZ1mn?arVSb%QC&`o45E8(794|t&BhF>=J&b*+AP`q}m5#&B6>+Z?Z7P&`
zSW+2>0)jxmm8@blS6k%3B}_n*SQ+sn@lv?UnY(h{KXV1WTITgVaTb$ls8Kh*HIpHM
z!Jv<fq&XV?*}VzHTsVMY@^8A`cT;=@G@O`CFN$9+@CR~V%_9wT%<<}{gVH{HZP|mf
z&Qf44KME&b{~Kd?OmH@VoQhnGO;7k4y_aj8^izA^GH!Sz6LqYg4wVR&1oNVyBab|K
z(7Z*n*`o+7a>ESX8Qk4SYjVk!R;K5?(U(M%S+iz7G?viiP0P(fHz%$eU)O9Z2NZcQ
zzx5;TA0VPZTKiJ}>y+5{P73eHX6^1k!u@I!IMU{!5{&7y!<yY+hKJrYtiHg9RO`L<
zsT_uvF41XRvER)By!Xb?)~5#+gd=9b7U40As`=Dq!Y1u}TqQEMy7^t_C5Hakitgad
z#`0y@3UP0zs{05cDPjuo!hMbPgb$)rB3UF%wN(1k&|sAWRx<qrF3in{ifB`f-)KN2
zTgzHleJt{>5F0r>escii{yq*zs%Jed;Yhr0)7$1oWO(I>I10W?k9*N}o8<v^hv@|&
z(=ylu3r!mL7xikiRuoVChqA5YeMOXt1fNtl7O<IdSq=PJPoiZREzyg9j-EjI)M4K_
zH9pSm38hM?=cSL*=d=ai+r)3Ux|e^}m#3o9S@@SgK4+Zz`9V@YNbTDND@TI-Z?MG<
z4UOOZ!F--h5xr$i07ZNe*}Vo%#X`6tn-(gnslTUmB0u<aOt*Tn2K{<n?|6AUSMzAg
zI)v){N6>{}_6z=e*N-<i7cLZpXC|UF*YxP6eT{eKz9^|s>cclfOz=a>pRM3EYd{6t
zCuR?a+H1J+8Z@97w$}-6n0%~>p1My9wp|o^JEsk#us_6A0)rV)ek>ZDeRt-zwtf&a
zK~|WxYSPxe4r7aMM(^P47SVXvZ+cQORp<3IAKTWj?LgM*ZH;q@>Dt;qRdDUDu?aDE
zx{|wTpwm(O1yh>3HVypF;fJA4$2aM5ldoR-o6If}=4~*8LR>9l^TTgL(wr_WBUY=5
zpcr<BO(-ON!BC31Ix>(T%HPo?;$ygi?1-%l(c0rqh(~eX6%R6}q(gPwzF#4RoVNGV
rue|zKHTFqG$Cu4FXcmY2EIN!d<HZvh96-c>uQ)(O0VH1mGz<J6V~0BS

literal 0
HcmV?d00001

diff --git a/mkdocs.yml b/mkdocs.yml
index 2eb0e8c..2f7336e 100644
--- a/mkdocs.yml
+++ b/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:
+                    - "!^_"
diff --git a/src/echosms/__init__.py b/src/echosms/__init__.py
index bd25701..214fbcf 100644
--- a/src/echosms/__init__.py
+++ b/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']
diff --git a/src/echosms/benchmarkdata.py b/src/echosms/benchmarkdata.py
index d31c1a8..244d5ef 100644
--- a/src/echosms/benchmarkdata.py
+++ b/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.
diff --git a/src/echosms/dcmmodel.py b/src/echosms/dcmmodel.py
index 9d97673..26cd52b 100644
--- a/src/echosms/dcmmodel.py
+++ b/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
         -----
diff --git a/src/echosms/mssmodel.py b/src/echosms/mssmodel.py
index 2798a92..dd80efc 100644
--- a/src/echosms/mssmodel.py
+++ b/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
diff --git a/src/echosms/psmsmodel.py b/src/echosms/psmsmodel.py
index 8545d21..704b357 100644
--- a/src/echosms/psmsmodel.py
+++ b/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
         -----
diff --git a/src/echosms/scattermodelbase.py b/src/echosms/scattermodelbase.py
index eb76e7b..c43d925 100644
--- a/src/echosms/scattermodelbase.py
+++ b/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).
 
     """
 
diff --git a/src/echosms/utils.py b/src/echosms/utils.py
index e9916f2..fc6a26d 100644
--- a/src/echosms/utils.py
+++ b/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].
diff --git a/src/example_code.py b/src/example_code.py
index 2b74a1d..abff6fc 100644
--- a/src/example_code.py
+++ b/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()