From c1b851e048b6c255311b4802496a83b08c30ce0d Mon Sep 17 00:00:00 2001
From: Vecko <36369090+VeckoTheGecko@users.noreply.github.com>
Date: Wed, 14 Aug 2024 16:15:45 +0200
Subject: [PATCH] Build API documentation

Also bugfix broken github link resolver
---
 .gitignore                |  6 +++++-
 .readthedocs.yaml         |  6 +++---
 docs/conf.py              | 14 +++++++++-----
 docs/environment_docs.yml |  2 +-
 docs/index.rst            |  5 +++--
 docs/reference.rst        | 33 +++++++++++++++++++++++++++++++++
 6 files changed, 54 insertions(+), 12 deletions(-)
 create mode 100644 docs/reference.rst

diff --git a/.gitignore b/.gitignore
index 447c55b..fbddf57 100644
--- a/.gitignore
+++ b/.gitignore
@@ -3,5 +3,9 @@ input_data/
 **.DS_store**
 **.pyc**
 **.zarr
+*.egg-info
+build
 docs/_build/*
-docs/_downloads
+.vscode
+_version_setup.py
+
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
index da7200d..ac52fdc 100644
--- a/.readthedocs.yaml
+++ b/.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
diff --git a/docs/conf.py b/docs/conf.py
index eb81286..3a2d29f 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -12,6 +12,10 @@
 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'
@@ -19,7 +23,6 @@
 # -- 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}"
         )
diff --git a/docs/environment_docs.yml b/docs/environment_docs.yml
index 1130cff..0b11b29 100644
--- a/docs/environment_docs.yml
+++ b/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
diff --git a/docs/index.rst b/docs/index.rst
index 59bb701..9272c04 100644
--- a/docs/index.rst
+++ b/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/>
diff --git a/docs/reference.rst b/docs/reference.rst
new file mode 100644
index 0000000..deeea30
--- /dev/null
+++ b/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
\ No newline at end of file