Merge pull request #47 from OceanParcels/v/api-ref

API reference

Author: michaeldenes

.flake8

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

.github/workflows/linting.yml

@@ -0,0 +1,16 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: trailing-whitespace
+      # - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-json
+        types: [text]
+        files: \.(json|ipynb)$
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.5.6
+    hooks:
+      - id: ruff
+        args: [ --fix ]
+      # - id: ruff-format

.gitignore

@@ -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

.pre-commit-config.yaml

@@ -13,6 +13,19 @@ The tool is based on the [`Parcels`](https://oceanparcels.org/) computational La
 conda install conda-forge::plasticparcels
 ```
 
+### Community contributions and support
+#### Contributing code
+We welcome contributions to `plasticparcels`, especially example workbooks and analyses for our [public examples page](https://plastic.oceanparcels.org/en/latest/examples.html). To contribute to the project, please submit a [pull request](https://github.com/OceanParcels/plasticparcels/pulls).
+
+#### Requesting features and reporting issues/bugs
+If you want to request a new feature, or if you find an issue or bug in the code, please open an issue in the [`plasticparcels` issue tracker](https://github.com/OceanParcels/plasticparcels/issues).
+
+#### Seeking support?
+If you would like support using `plasticparcels`, or are have any questions about your `plasticparcels` simulations, please start a discussion in the [`plasticparcels` discussion page](https://github.com/OceanParcels/plasticparcels/discussions).
+
+
+
+
 ### Further information
 For more information and documentation, see the [plasticparcels documentation](https://plastic.oceanparcels.org/).
 

.readthedocs.yaml

@@ -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}"
         )

README.md

@@ -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/conf.py

@@ -31,14 +31,21 @@ 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>`_.
 
 To run the examples, you will need to update the data directories in settings ``.json`` files.
 
-Just like the ``parcels`` framework, ``plasticparcels`` can be adapted to use other hydrodynamic, biogeochemical, wave, and atmospheric models. If you require assistance, please contact us through the [Discussions page on GitHub](https://github.com/OceanParcels/plasticparcels/discussions).
+Just like the ``parcels`` framework, ``plasticparcels`` can be adapted to use other hydrodynamic, biogeochemical, wave, and atmospheric models. If you require assistance, please contact us through the `Discussions page on GitHub <https://github.com/OceanParcels/plasticparcels/discussions>`_.
+
+Community Guidelines
+^^^^^^^^^^^^^^^^^^^^
+
+We welcome contributions to ``plasticparcels``, especially example workbooks and analyses for our `public examples page <https://plastic.oceanparcels.org/en/latest/examples.html>`_. To contribute to the project, please submit a `pull request <https://github.com/OceanParcels/plasticparcels/pulls>`_.
+If you want to request a new feature, or if you find an issue or bug in the code, please open an issue in the `plasticparcels issue tracker <https://github.com/OceanParcels/plasticparcels/issues>`_.
+If you would like support using ``plasticparcels``, or are have any questions about your ``plasticparcels`` simulations, please start a discussion in the `plasticparcels discussion page <https://github.com/OceanParcels/plasticparcels/discussions>`_.
 
 .. toctree::
    :maxdepth: 2
@@ -48,4 +55,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/index>
    OceanParcels website <https://oceanparcels.org/>

docs/environment_docs.yml

@@ -0,0 +1,6 @@
+plasticparcels.constructors
+---------------------------
+
+.. automodule:: plasticparcels.constructors
+    :members:
+    :show-inheritance: yes