Build API documentation

Also bugfix broken github link resolver

.gitignore

@@ -3,5 +3,9 @@ input_data/
 **.DS_store**
 **.pyc**
 **.zarr
+*.egg-info
+build
 docs/_build/*
-docs/_downloads
+.vscode
+_version_setup.py
+

.readthedocs.yaml

@@ -3,9 +3,9 @@ build:
   os: ubuntu-22.04
   tools:
     python: mambaforge-22.9
-  # jobs:  # TODO: uncomment when we have a test suite
-  #   pre_build:
-  #     - sphinx-build -b linkcheck docs/ _build/linkcheck
+  jobs:
+    pre_build:
+      - pip install . # Need access to version information
 
 sphinx:
   configuration: docs/conf.py

docs/conf.py

@@ -12,14 +12,17 @@
 import sys
 import warnings
 
+sys.path.insert(0, os.path.abspath('..')) # Allow to find `plasticparcels` package
+
+import plasticparcels
+
 project = 'plasticparcels'
 copyright = f'{datetime.datetime.now().year}, The OceanParcels Team'
 author = 'The OceanParcels Team'
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-extensions = []
 
 templates_path = ['_templates']
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
@@ -78,6 +81,7 @@
     "myst_parser",
     "nbsphinx",
     "numpydoc",
+    'sphinx.ext.autosummary',
 ]
 
 myst_enable_extensions = ["dollarmath", "amsmath"]
@@ -130,12 +134,12 @@ def linkcode_resolve(domain, info):
     else:
         linespec = ""
 
-    fn = os.path.relpath(fn, start=os.path.dirname(parcels.__file__))
+    fn = os.path.relpath(fn, start=os.path.dirname(plasticparcels.__file__))
 
-    if "-" in parcels.__version__:
-        return f"https://github.com/OceanParcels/plasticparcels/blob/master/parcels/{fn}{linespec}"
+    if "-" in plasticparcels.__version__:
+        return f"https://github.com/OceanParcels/plasticparcels/blob/master/plasticparcels/{fn}{linespec}"
     else:
         return (
             f"https://github.com/OceanParcels/plasticparcels/blob/"
-            f"{parcels.__version__}/parcels/{fn}{linespec}"
+            f"{plasticparcels.__version__}/plasticparcels/{fn}{linespec}"
         )

docs/environment_docs.yml

@@ -27,7 +27,7 @@ dependencies:
   - numpydoc
   - nbsphinx
   - sphinx<6
-  - pandoc>1.12.1,<3
+  - pandoc>3,<4
   - pydata-sphinx-theme
   - sphinx-autobuild
   - myst-parser

docs/index.rst

@@ -31,8 +31,8 @@ Required Data
 
 * Hydrodynamic model data: `MOI GLO12 (psy4v3r1) <https://www.mercator-ocean.eu/en/solutions-expertise/accessing-digital-data/product-details/?offer=4217979b-2662-329a-907c-602fdc69c3a3&system=d35404e4-40d3-59d6-3608-581c9495d86a>`_
 * Biogeochemical model data: `MOI BIO4 (biomer4v2r1) <https://www.mercator-ocean.eu/en/solutions-expertise/accessing-digital-data/product-details/?offer=8d0c01f3-81c7-0a59-0d06-602fdf63c5b6&system=dc40b324-7de7-0732-880b-5d9dcf7d344a>`_
-* Wave data: `ECMWF ERA5 Wave <https://cds.climate.copernicus.eu/cdsapp#!/dataset/reanalysis-era5-single-levels>`_ (specifically, the variables ``mean_wave_period``, ``peak_wave_period``, ``u_component_stokes_drift``, and ``v_component_stokes_drift``.) 
-* Wind data: `ECMWF ERA5 Wind <https://cds.climate.copernicus.eu/cdsapp#!/dataset/reanalysis-era5-single-levels>`_ (specifically, the variables ``10m_u_component_of_wind`` and ``10m_v_component_of_wind``) 
+* Wave data: `ECMWF ERA5 Wave <https://cds.climate.copernicus.eu/cdsapp#!/dataset/reanalysis-era5-single-levels>`_ (specifically, the variables ``mean_wave_period``, ``peak_wave_period``, ``u_component_stokes_drift``, and ``v_component_stokes_drift``.)
+* Wind data: `ECMWF ERA5 Wind <https://cds.climate.copernicus.eu/cdsapp#!/dataset/reanalysis-era5-single-levels>`_ (specifically, the variables ``10m_u_component_of_wind`` and ``10m_v_component_of_wind``)
 
 For the wind and wave data, we recommend using the `CDS API <https://cds.climate.copernicus.eu/api-how-to>`_.
 
@@ -48,4 +48,5 @@ Just like the ``parcels`` framework, ``plasticparcels`` can be adapted to use ot
    Examples <examples>
    Physics kernels <physicskernels>
    Plastic initialisation maps <initialisationmaps>
+   API reference <reference>
    OceanParcels website <https://oceanparcels.org/>

docs/reference.rst

@@ -0,0 +1,33 @@
+API
+===
+
+plasticparcels.constructors
+---------------------------
+
+.. automodule:: plasticparcels.constructors
+    :members:
+    :show-inheritance: yes
+
+
+plasticparcels.kernels
+---------------------------
+
+.. automodule:: plasticparcels.kernels
+    :members:
+    :show-inheritance: yes
+
+
+plasticparcels.particlefile
+---------------------------
+
+.. automodule:: plasticparcels.particlefile
+    :members:
+    :show-inheritance: yes
+
+
+plasticparcels.utils
+---------------------------
+
+.. automodule:: plasticparcels.utils
+    :members:
+    :show-inheritance: yes