OceanParcels · VeckoTheGecko · Apr 2, 2023 · Mar 20, 2023 · Mar 26, 2023 · Mar 26, 2023
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -10,7 +10,10 @@ repos:
     rev: '6.0.0'
     hooks:
     -   id: flake8
-        additional_dependencies: ["flake8-docstrings"]
+-   repo: https://github.com/pycqa/pydocstyle
+    rev: 4.0.0  # pick a git hash / tag to point to
+    hooks:
+    -   id: pydocstyle
 -   repo: https://github.com/pycqa/isort
     rev: 5.12.0
     hooks:

diff --git a/docs/Makefile b/docs/Makefile
@@ -5,7 +5,7 @@
 SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
 PAPER         =
-BUILDDIR      = ../../oceanparcels_website/gh-pages
+BUILDDIR      = _build
 
 # User-friendly check for sphinx-build
 ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)

diff --git a/docs/conf.py b/docs/conf.py
@@ -33,6 +33,8 @@
     'sphinx.ext.autodoc',
     'sphinx.ext.todo',
     "sphinx.ext.linkcode",
+    "sphinx.ext.napoleon",
+    "numpydoc",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -98,7 +100,7 @@
 # show_authors = False
 
 # The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'sphinx'
+pygments_style = 'monokai'
 
 # A list of ignored prefixes for module index sorting.
 # modindex_common_prefix = []
@@ -109,7 +111,6 @@
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = True
 
-
 # -- Options for HTML output ----------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
@@ -137,6 +138,21 @@
 # pixels large.
 # html_favicon = None
 
+# numpydoc support
+# ----------------
+numpydoc_class_members_toctree = False  # https://stackoverflow.com/a/73294408
+
+# full list of numpydoc error codes: https://numpydoc.readthedocs.io/en/latest/validation.html
+numpydoc_validation_checks = {
+    "GL05",
+    "GL06",
+    "GL07",
+    "GL10",
+    "PR05",
+    "PR10",
+    "RT02",
+}
+
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".

diff --git a/docs/index.rst b/docs/index.rst
@@ -199,14 +199,14 @@ parcels.plotting module
     :undoc-members:
 
 parcels.scripts.plottrajectoriesfile module
------------------------------------
+-------------------------------------------
 
 .. automodule:: parcels.scripts.plottrajectoriesfile
     :members:
     :undoc-members:
 
 parcels.scripts.get_examples module
----------------------------
+-----------------------------------
 
 .. automodule:: parcels.scripts.get_examples
     :members:

diff --git a/docs/make.bat b/docs/make.bat
@@ -5,7 +5,7 @@ REM Command file for Sphinx documentation
 if "%SPHINXBUILD%" == "" (
 	set SPHINXBUILD=sphinx-build
 )
-set BUILDDIR=../../oceanparcels_website/gh-pages
+set BUILDDIR=_build
 set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% .
 set I18NSPHINXOPTS=%SPHINXOPTS% .
 if NOT "%PAPER%" == "" (

diff --git a/environment_py3_linux.yml b/environment_py3_linux.yml
@@ -38,10 +38,11 @@ dependencies:
 
   # Linting
   - flake8>=2.1.0
-  - flake8-docstrings
   - pre_commit
+  - pydocstyle
 
   # Docs
+  - numpydoc
   - sphinx<6
   - pydata-sphinx-theme
   - sphinx-autobuild
diff --git a/environment_py3_osx.yml b/environment_py3_osx.yml
@@ -38,10 +38,11 @@ dependencies:
 
   # Linting
   - flake8>=2.1.0
-  - flake8-docstrings
   - pre_commit
+  - pydocstyle
 
   # Docs
+  - numpydoc
   - sphinx<6
   - pydata-sphinx-theme
   - sphinx-autobuild
diff --git a/environment_py3_win.yml b/environment_py3_win.yml
@@ -35,10 +35,11 @@ dependencies:
 
   # Linting
   - flake8>=2.1.0
-  - flake8-docstrings
   - pre_commit
+  - pydocstyle
 
   # Docs
+  - numpydoc
   - sphinx<6
   - pydata-sphinx-theme
   - sphinx-autobuild
diff --git a/parcels/application_kernels/EOSseawaterproperties.py b/parcels/application_kernels/EOSseawaterproperties.py
@@ -11,14 +11,13 @@ def PressureFromLatDepth(particle, fieldset, time):
     Returns
     -------
     p : array_like
-           pressure [db]
+        pressure [db]
 
     References
     ----------
-    .. [1] Saunders, Peter M., 1981: Practical Conversion of Pressure to Depth.
+    1. Saunders, Peter M., 1981: Practical Conversion of Pressure to Depth.
        J. Phys. Oceanogr., 11, 573-574.
        doi: 10.1175/1520-0485(1981)011<0573:PCOPTD>2.0.CO;2
-
     """
     # Angle conversions.
     deg2rad = math.pi / 180.0
@@ -29,31 +28,36 @@ def PressureFromLatDepth(particle, fieldset, time):
 
 
 def AdiabticTemperatureGradient(particle, fieldset, time):
-    """
-    Calculates adiabatic temperature gradient as per UNESCO 1983 routines.
+    """Calculates adiabatic temperature gradient as per UNESCO 1983 routines.
+
 
     Parameters
     ----------
-    :param particle.S: salinity [psu (PSS-78)]
-    :type particle.S: array_like
-    :param particle.T: temperature [℃ (ITS-90)]
-    :type particle.T: array_like
-    :param particle.pressure: pressure [db]
-    :type particle.pressure: array_like
+    particle :
+        The particle object with the following attributes:
+            - S : array_like
+                Salinity in psu (PSS-78).
+            - T : array_like
+                Temperature in ℃ (ITS-90).
+            - pressure : array_like
+                Pressure in db.
+    fieldset :
+        The fieldset object
 
     Returns
     -------
-    :return: adiabatic temperature gradient [℃ db :sup:`-1`]
-    :type: array_like
+    array_like
+        Adiabatic temperature gradient in ℃ db⁻¹.
+
 
     References
     ----------
-    .. [1] Fofonoff, P. and Millard, R.C. Jr UNESCO 1983. Algorithms for
+    1. Fofonoff, P. and Millard, R.C. Jr UNESCO 1983. Algorithms for
        computation of fundamental properties of seawater. UNESCO Tech. Pap. in
        Mar. Sci., No. 44, 53 pp.
        http://unesdoc.unesco.org/images/0005/000598/059832eb.pdf
 
-    .. [2] Bryden, H. 1973. New Polynomials for thermal expansion, adiabatic
+    2. Bryden, H. 1973. New Polynomials for thermal expansion, adiabatic
        temperature gradient and potential temperature of sea water. Deep-Sea
        Res. Vol20,401-408. doi:10.1016/0011-7471(73)90063-6
 
@@ -80,28 +84,35 @@ def PtempFromTemp(particle, fieldset, time):
 
     Parameters
     ----------
-    :param particle.S: salinity [psu (PSS-78)]
-    :type particle.S: array_like
-    :param particle.T: temperature [℃ (ITS-90)]
-    :type particle.T: array_like
-    :param particle.pressure: pressure [db]
-    :type particle.pressure: array_like
-    :param fieldset.refpressure: reference pressure [db], default = 0
-    :type fieldset.refpressure: array_like
+    particle :
+        The particle object with the following attributes:
+            - S : array_like
+                Salinity in psu (PSS-78).
+            - T : array_like
+                Temperature in ℃ (ITS-90).
+            - pressure : array_like
+                Pressure in db.
+    fieldset :
+        The fieldset object with the following attributes:
+            - refpressure : array_like, optional
+                Reference pressure in db (default is 0).
+    time : float
+        Simulation time (not used in this function but required for consistency with other kernels).
 
     Returns
     -------
-    :return: potential temperature relative to PR [℃ (ITS-90)]
-    :type: array_like
+    array_like
+        Potential temperature relative to reference pressure in ℃ (ITS-90).
+
 
     References
     ----------
-    .. [1] Fofonoff, P. and Millard, R.C. Jr UNESCO 1983. Algorithms for
+    1. Fofonoff, P. and Millard, R.C. Jr UNESCO 1983. Algorithms for
        computation of fundamental properties of seawater. UNESCO Tech. Pap. in
        Mar. Sci., No. 44, 53 pp.  Eqn.(31) p.39.
        http://unesdoc.unesco.org/images/0005/000598/059832eb.pdf
 
-    .. [2] Bryden, H. 1973. New Polynomials for thermal expansion, adiabatic
+    2. Bryden, H. 1973. New Polynomials for thermal expansion, adiabatic
        temperature gradient and potential temperature of sea water. Deep-Sea
        Res. Vol20,401-408. doi:10.1016/0011-7471(73)90063-6
 
@@ -173,28 +184,34 @@ def TempFromPtemp(particle, fieldset, time):
 
     Parameters
     ----------
-    :param particle.S: salinity [psu (PSS-78)]
-    :type particle.S: array_like
-    :param particle.T: potential temperature [℃ (ITS-90)]
-    :type particle.T: array_like
-    :param particle.pressure: pressure [db]
-    :type particle.pressure: array_like
-    :param fieldset.refpressure: reference pressure [db], default = 0
-    :type fieldset.refpressure: array_like
+    particle :
+        The particle object with the following attributes:
+            - S : array_like
+                Salinity in psu (PSS-78).
+            - T : array_like
+                Potential temperature in ℃ (ITS-90).
+            - pressure : array_like
+                Pressure in db.
+    fieldset :
+        The fieldset object with the following attributes:
+            - refpressure : array_like, optional
+                Reference pressure in db (default is 0).
+    time : float
+        Simulation time (not used in this function but required for consistency with other kernels).
 
     Returns
     -------
-    :return: temperature [℃ (ITS-90)]
-    :type: array_like
+    array_like
+        Temperature in ℃ (ITS-90).
 
     References
     ----------
-    .. [1] Fofonoff, P. and Millard, R.C. Jr UNESCO 1983. Algorithms for
+    1. Fofonoff, P. and Millard, R.C. Jr UNESCO 1983. Algorithms for
        computation of fundamental properties of seawater. UNESCO Tech. Pap. in
        Mar. Sci., No. 44, 53 pp.  Eqn.(31) p.39.
        http://unesdoc.unesco.org/images/0005/000598/059832eb.pdf
 
-    .. [2] Bryden, H. 1973. New Polynomials for thermal expansion, adiabatic
+    2. Bryden, H. 1973. New Polynomials for thermal expansion, adiabatic
        temperature gradient and potential temperature of sea water. Deep-Sea
        Res.  Vol20,401-408. doi:10.1016/0011-7471(73)90063-6
 

diff --git a/parcels/application_kernels/TEOSseawaterdensity.py b/parcels/application_kernels/TEOSseawaterdensity.py
@@ -5,20 +5,22 @@
 
 
 def PolyTEOS10_bsq(particle, fieldset, time):
-    """
-    Calculates density based on the polyTEOS10-bsq algorithm from Appendix A.2 of
+    """Calculates density based on the polyTEOS10-bsq algorithm from Appendix A.2 of
     https://www.sciencedirect.com/science/article/pii/S1463500315000566
     requires fieldset.abs_salinity and fieldset.cons_temperature Fields in the fieldset
     and a particle.density Variable in the ParticleSet
 
-    References:
-    Roquet, F., Madec, G., McDougall, T. J., Barker, P. M., 2014: Accurate
-    polynomial expressions for the density and specific volume of
-    seawater using the TEOS-10 standard. Ocean Modelling.
-    McDougall, T. J., D. R. Jackett, D. G. Wright and R. Feistel, 2003:
-    Accurate and computationally efficient algorithms for potential
-    temperature and density of seawater.  Journal of Atmospheric and
-    Oceanic Technology, 20, 730-741.
+    References
+    ----------
+    1. Roquet, F., Madec, G., McDougall, T. J., Barker, P. M., 2014: Accurate
+       polynomial expressions for the density and specific volume of
+       seawater using the TEOS-10 standard. Ocean Modelling.
+
+    2. McDougall, T. J., D. R. Jackett, D. G. Wright and R. Feistel, 2003:
+       Accurate and computationally efficient algorithms for potential
+       temperature and density of seawater.  Journal of Atmospheric and
+       Oceanic Technology, 20, 730-741.
+
     """
     Z = - math.fabs(particle.depth)  # Z needs to be negative
     SA = fieldset.abs_salinity[time, particle.depth, particle.lat, particle.lon]

diff --git a/parcels/application_kernels/advectiondiffusion.py b/parcels/application_kernels/advectiondiffusion.py
@@ -1,6 +1,6 @@
 """Collection of pre-built advection-diffusion kernels.
 
-See `this tutorial <https://nbviewer.jupyter.org/github/OceanParcels/parcels/blob/master/parcels/examples/tutorial_diffusion.ipynb>`_ for a detailed explanation.
+See `this tutorial <https://nbviewer.jupyter.org/github/OceanParcels/parcels/blob/master/parcels/examples/tutorial_diffusion.ipynb>`__ for a detailed explanation.
 """
 import math
 
@@ -87,9 +87,9 @@ def DiffusionUniformKh(particle, fieldset, time):
 
     Assumes that fieldset has constant fields `Kh_zonal` and `Kh_meridional`.
     These can be added via e.g.
-        fieldset.add_constant_field("Kh_zonal", kh_zonal, mesh=mesh)
-
-        fieldset.add_constant_field("Kh_meridional", kh_meridional, mesh=mesh)
+    `fieldset.add_constant_field("Kh_zonal", kh_zonal, mesh=mesh)`
+    or
+    `fieldset.add_constant_field("Kh_meridional", kh_meridional, mesh=mesh)`
     where mesh is either 'flat' or 'spherical'
 
     This kernel assumes diffusivity gradients are zero and is therefore more efficient.