fix docs (#110)

- update to newer sphinxcontrib-bibtex
- fix gh pr references
- update readthedocs environment
- fix a few docstrings
- cosmetic changes for some references

.readthedocs.yml

@@ -19,6 +19,6 @@ sphinx:
 python:
   install:
     - requirements: requirements.txt
-    - requirements: requirements_rtd.txt
+    - requirements: requirements_docs.txt
     - method: pip
       path: .

docs/conf.py

@@ -62,8 +62,8 @@
 nbsphinx_kernel_name = "python3"
 
 extlinks = {
-    "issue": ("https://github.com/modscripps/mixsea/issues/%s", "GH"),
-    "pull": ("https://github.com/modscripps/mixsea/pull/%s", "PR"),
+    "issue": ("https://github.com/modscripps/mixsea/issues/%s", "GH%s"),
+    "pull": ("https://github.com/modscripps/mixsea/pull/%s", "PR%s"),
 }
 
 ipython_savefig_dir = os.path.join(

docs/references.bib

@@ -12,7 +12,7 @@ @article{voetetal15
 @article{Ferron1998,
 author = {Ferron, B. and Mercier, H. and Speer, K. and Gargett, A. and Polzin, K.},
 doi = {10.1175/1520-0485(1998)028<1929:MITRFZ>2.0.CO;2},
-journal = {Journal of Physical Oceanography},
+journal = {J. Phys. Oceanogr.},
 number = {10},
 pages = {1929--1945},
 title = {{Mixing in the Romanche Fracture Zone}},
@@ -22,8 +22,9 @@ @article{Ferron1998
 
 @article{Garrett1975,
   title={Space-time scales of internal waves: A progress report},
-  author={Garrett, Christopher and Munk, Walter},
-  journal={Journal of Geophysical Research},
+  doi={https://doi.org/10.1029/JC080i003p00291},
+  author={Garrett, C. and Munk, W.},
+  journal={J. Geophys. Res.},
   volume={80},
   number={3},
   pages={291--297},
@@ -33,8 +34,9 @@ @article{Garrett1975
 
 @article{Polzin2004,
   title={A heuristic description of internal wave dynamics},
-  author={Polzin, Kurt},
-  journal={Journal of physical oceanography},
+  doi={https://doi.org/10.1175/1520-0485(2004)034%3C0214:AHDOIW%3E2.0.CO;2},
+  author={Polzin, K.},
+  journal={J. Phys. Oceanogr.},
   volume={34},
   number={1},
   pages={214--230},
@@ -43,21 +45,20 @@ @article{Polzin2004
 
 @article{Henyey1986,
   title={Energy and action flow through the internal wave field: An eikonal approach},
-  author={Henyey, Frank S and Wright, Jon and Flatt{\'e}, Stanley M},
-  journal={Journal of Geophysical Research: Oceans},
+  doi={https://doi.org/10.1029/JC091iC07p08487},
+  author={Henyey, F. S. and Wright, J. and Flatt{\'e}, S. M.},
+  journal={J. Geophys. Res.},
   volume={91},
   number={C7},
   pages={8487--8495},
   year={1986},
   publisher={Wiley Online Library}
 }
 
-
-
 @article{Gargett2008,
 author = {Gargett, A. and Garner, T.},
 doi = {10.1175/2008JTECHO541.1},
-journal = {Journal of Atmospheric and Oceanic Technology},
+journal = {J. Atmos. Oceanic Technol.},
 number = {9},
 pages = {1657--1670},
 title = {{Determining Thorpe Scales from Ship-Lowered CTD Density Profiles}},
@@ -68,7 +69,7 @@ @article{Gargett2008
 @article{Smyth2001,
 author = {Smyth, W. D. and Moum, J. N. and Caldwell, D. R.},
 doi = {10.1175/1520-0485(2001)031<1969:TEOMIT>2.0.CO;2},
-journal = {Journal of Physical Oceanography},
+journal = {J. Phys. Oceanogr.},
 number = {8},
 pages = {1969--1992},
 title = {{The Efficiency of Mixing in Turbulent Patches: Inferences from Direct Simulations and Microstructure Observations}},
@@ -77,7 +78,7 @@ @article{Smyth2001
 }
 
 @article{Gregg2003,
-Author = {Gregg, M. C. and T. B. Sanford and D. P. Winkel},
+Author = {Gregg, M. C. and Sanford, T. B. and Winkel, D. P.},
 doi = {10.1038/nature01507},
 Journal = {Nature},
 Number = {3},
@@ -99,7 +100,7 @@ @article{Bray1981
 }
 
 @article{Kunze2006,
-Author = {E. Kunze and E. Firing and J. Hummon and T. K. Chereskin and A. Thurnherr},
+Author = {Kunze, E. and Firing, E. and Hummon, J. and Chereskin, T. K. and Thurnherr, A.},
 Journal = {J. Phys. Oceanogr.},
 Number = {8},
 Pages = {1553--1576},
@@ -109,7 +110,6 @@ @article{Kunze2006
 doi = {doi.org/10.1175/JPO2926.1}
 }
 
-
 @article{Gargett1990,
 Author = {Gargett, A. E.},
 doi = {10.1029/jc095ic09p15971},
@@ -122,10 +122,9 @@ @article{Gargett1990
 }
 
 @article{Thorpe1977,
-author = {Thorpe, S A},
+author = {Thorpe, S. A.},
 doi = {10.2307/74802},
-journal = {Philosophical Transactions of the Royal Society of London. Series A, Mathematical and Physical Sciences},
-month = {jul},
+journal = {Philos. Trans. R. Soc. London, Ser. A},
 number = {1334},
 pages = {125--181},
 publisher = {The Royal Society},

docs/zzreferences.rst

@@ -1,5 +1,5 @@
 References
 ==========
 
-.. bibliography:: references.bib
-    :style: plain
+.. bibliography::
+    :style: plain

environment_docs.yml

@@ -0,0 +1,10 @@
+name: mixsea-docs
+channels:
+  - conda-forge
+dependencies:
+  - python=3.11
+  - pip
+  - pip:
+    - -r requirements.txt
+    - -r requirements_docs.txt
+    - -e .

mixsea/shearstrain.py

@@ -56,18 +56,19 @@ def strain_polynomial_fits(depth, t, SP, lon, lat, depth_bin, window_size):
     -------
     list
         List with results in a dict for each depth segment. The dict has the following entries:
-        ``"segz"``
-            Segment depth vector (`array-like`).
-        ``"depth_bin"``
-            Segment center depth (`float`).
-        ``"N2"``
-            Segment buoyancy frequency squared (`array-like`).
-        ``"N2smooth"``
-            Segment polynomial fit to buoyancy frequency squared (`array-like`).
-        ``"N2mean"``
-            Segment mean buoyancy frequency squared (`float`).
-        ``"strain"``
-            Segment strain (`array-like`).
+
+        - ``"segz"``: Segment depth vector (`array-like`).
+
+        - ``"depth_bin"``: Segment center depth (`float`).
+
+        - ``"N2"``: Segment buoyancy frequency squared (`array-like`).
+
+        - ``"N2smooth"``: Segment polynomial fit to buoyancy frequency squared (`array-like`).
+
+        - ``"N2mean"``: Segment mean buoyancy frequency squared (`float`).
+
+        - ``"strain"``: Segment strain (`array-like`).
+
     """
     # Prepare output list. It will hold a dictionary with data for each window.
     out = []
@@ -125,18 +126,18 @@ def strain_adiabatic_leveling(
     -------
     list
         List with results in a dict for each depth segment. The dict has the following entries:
-        ``"segz"``
-            Segment depth vector (`array-like`).
-        ``"depth_bin"``
-            Segment center depth (`float`).
-        ``"N2"``
-            Segment buoyancy frequency squared (`array-like`).
-        ``"N2smooth"``
-            Segment polynomial fit to buoyancy frequency squared (`array-like`).
-        ``"N2mean"``
-            Segment mean buoyancy frequency squared (`float`).
-        ``"strain"``
-            Segment strain (`array-like`).
+
+        - ``"segz"``: Segment depth vector (`array-like`).
+
+        - ``"depth_bin"``: Segment center depth (`float`).
+
+        - ``"N2"``: Segment buoyancy frequency squared (`array-like`).
+
+        - ``"N2smooth"``: Segment polynomial fit to buoyancy frequency squared (`array-like`).
+        - ``"N2mean"``: Segment mean buoyancy frequency squared (`float`).
+
+        - ``"strain"``: Segment strain (`array-like`).
+
     """
     dz = np.absolute(np.median(np.diff(depth)))
     # Prepare output list. It will hold a dictionary with data for each window.

requirements_rtd.txt → requirements_docs.txt

@@ -3,7 +3,7 @@ matplotlib
 pandoc
 sphinx
 sphinx_rtd_theme
-sphinxcontrib-bibtex<2.0.0
+sphinxcontrib-bibtex
 nbsphinx
 pandoc
 argh