From 95afa392db91d29cb4a4f988ef28b4b641d1fda8 Mon Sep 17 00:00:00 2001 From: Gunnar Voet Date: Tue, 21 Nov 2023 20:11:05 -0800 Subject: [PATCH] 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 | 2 +- docs/conf.py | 4 +- docs/references.bib | 33 ++++++------- docs/zzreferences.rst | 4 +- environment_docs.yml | 10 ++++ environment_rtfd.yml | 13 ----- mixsea/shearstrain.py | 49 ++++++++++--------- requirements_rtd.txt => requirements_docs.txt | 2 +- 8 files changed, 57 insertions(+), 60 deletions(-) create mode 100644 environment_docs.yml delete mode 100644 environment_rtfd.yml rename requirements_rtd.txt => requirements_docs.txt (74%) diff --git a/.readthedocs.yml b/.readthedocs.yml index a9105bc..f242f03 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -19,6 +19,6 @@ sphinx: python: install: - requirements: requirements.txt - - requirements: requirements_rtd.txt + - requirements: requirements_docs.txt - method: pip path: . diff --git a/docs/conf.py b/docs/conf.py index 50dd99b..d30923f 100755 --- a/docs/conf.py +++ b/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( diff --git a/docs/references.bib b/docs/references.bib index 38234b3..6c488f2 100644 --- a/docs/references.bib +++ b/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,8 +45,9 @@ @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}, @@ -52,12 +55,10 @@ @article{Henyey1986 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}, diff --git a/docs/zzreferences.rst b/docs/zzreferences.rst index 5d322f0..3631547 100644 --- a/docs/zzreferences.rst +++ b/docs/zzreferences.rst @@ -1,5 +1,5 @@ References ========== -.. bibliography:: references.bib - :style: plain \ No newline at end of file +.. bibliography:: + :style: plain diff --git a/environment_docs.yml b/environment_docs.yml new file mode 100644 index 0000000..acecdb9 --- /dev/null +++ b/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 . diff --git a/environment_rtfd.yml b/environment_rtfd.yml deleted file mode 100644 index ba3bc00..0000000 --- a/environment_rtfd.yml +++ /dev/null @@ -1,13 +0,0 @@ -name: mixsea-rtfd -channels: - - conda-forge -dependencies: - - python=3.8 - - numpy>=1.15 - - gsw - - scipy - - matplotlib>=3.4.0 - - ipykernel - - sphinxcontrib-bibtex<2.0.0 - - nbsphinx - - pandoc diff --git a/mixsea/shearstrain.py b/mixsea/shearstrain.py index e352d8d..b848ae7 100644 --- a/mixsea/shearstrain.py +++ b/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. diff --git a/requirements_rtd.txt b/requirements_docs.txt similarity index 74% rename from requirements_rtd.txt rename to requirements_docs.txt index 6921c98..b8b0f03 100644 --- a/requirements_rtd.txt +++ b/requirements_docs.txt @@ -3,7 +3,7 @@ matplotlib pandoc sphinx sphinx_rtd_theme -sphinxcontrib-bibtex<2.0.0 +sphinxcontrib-bibtex nbsphinx pandoc argh