Merge remote-tracking branch 'upstream/v4-dev' into pixi-docs

Author: VeckoTheGecko

.github/ISSUE_TEMPLATE/01_feature.md

@@ -2,6 +2,6 @@
 name: 🔼 Parcels feature requests, and other enhancements
 about: Suggest an improvement to the parcels codebase.
 title: ""
-labels: ""
+labels: ["needs-triage"]
 assignees: ""
 ---

.github/ISSUE_TEMPLATE/02_bug.yaml

@@ -1,6 +1,6 @@
 name: "🐛 Bug Report"
 description: Describe a bug in the parcels codebase. For support related to your specific use case, please post in Q&A in our Discussions tab.
-labels: ["bug"]
+labels: ["bug", "needs-triage"]
 body:
   - type: "input"
     attributes:

docs/community/contributing.md

@@ -6,17 +6,17 @@
 
 The Parcels code, for which development started in 2015, is now one of the most widely used tools for Lagrangian Ocean Analysis. It's used by dozens of groups around the world - see [this list](https://oceanparcels.org/papers-citing-parcels#papers-citing-parcels) for a full list of the peer-reviewed articles using Parcels. Its flexibility for users to create new, custom 'behaviours' (i.e. let virtual particles be controlled by other mechanics than only the ocean flow) and its compatibility with many different types of hydrodynamic input data are the two key features.
 
-> **Note**
->
-> Want to learn more about Lagrangian ocean analysis? Then look at [Lagrangian ocean analysis: Fundamentals and practices](https://www.sciencedirect.com/science/article/pii/S1463500317301853) for a review of the literature.
+```{note}
+Want to learn more about Lagrangian ocean analysis? Then look at [Lagrangian ocean analysis: Fundamentals and practices](https://www.sciencedirect.com/science/article/pii/S1463500317301853) for a review of the literature.
+```
 
 ---
 
 There are two primary groups that contribute to Parcels; oceanographers who bring domain specific understanding about the physical processes and modelling approaches, as well as software developers who bring their experience working with code. **All contributions are welcome no matter your background or level of experience**.
 
-> **Note**
->
-> The first component of this documentation is geared to those new to open source. Already familiar with GitHub and open source? Skip ahead to the [Development](#development) section.
+```{note}
+The first component of this documentation is geared to those new to open source. Already familiar with GitHub and open source? Skip ahead to the [Development](#development) section.
+```
 
 ## What is open source?
 
@@ -37,8 +37,8 @@ Exactly how to use Git and GitHub is beyond the scope of this documentation, and
 There are many ways that you can contribute to Parcels. You can:
 
 - Participate in discussion about Parcels, either through the [issues](https://github.com/OceanParcels/parcels/issues) or [discussions](https://github.com/OceanParcels/parcels/discussions) tab
-- Suggest improvements to [tutorials](../documentation/index.rst)
-- Suggest improvements to [documentation](../index.rst)
+- Suggest improvements to [tutorials](../documentation/index.md)
+- Suggest improvements to [documentation](../index.md)
 - Write code (fix bugs, implement features, codebase improvements, etc)
 
 All of these require you to [make an account on GitHub](https://github.com/signup), so that should be your first step.
@@ -53,9 +53,9 @@ In the [Projects panel](https://github.com/OceanParcels/parcels/projects?query=i
 
 ### Environment setup
 
-> **Note**
->
-> Parcels, alongside popular projects like [Xarray](https://github.com/pydata/xarray), uses [Pixi](https://pixi.sh) to manage environments and run developer tooling. Pixi is a modern alternative to Conda and also includes other powerful tooling useful for a project like Parcels ([read more](https://github.com/OceanParcels/Parcels/issues/2205)). It is our sole development workflow - we do not offer a Conda development workflow. Give Pixi a try, you won't regret it!
+```{note}
+Parcels, alongside popular projects like [Xarray](https://github.com/pydata/xarray), uses [Pixi](https://pixi.sh) to manage environments and run developer tooling. Pixi is a modern alternative to Conda and also includes other powerful tooling useful for a project like Parcels ([read more](https://github.com/OceanParcels/Parcels/issues/2205)). It is our sole development workflow - we do not offer a Conda development workflow. Give Pixi a try, you won't regret it!
+```
 
 To get started contributing to Parcels:
 
@@ -83,9 +83,9 @@ Now you have a development installation of Parcels, as well as a bunch of develo
 4. If you've added new features, run `pixi run typing` to check type annotations
 5. If you've modified documentation, run `pixi run docs` to build and verify the docs
 
-> **Tip**
->
-> You can run `pixi info` to see all available environments and `pixi task list` to see all available tasks across environments.
+```{tip}
+You can run `pixi info` to see all available environments and `pixi task list` to see all available tasks across environments.
+```
 
 See below for more Pixi commands relevant to development.
 
@@ -114,9 +114,9 @@ Parcels supports testing against different environments (e.g., different Python
 
 The name of the workflow on GitHub contains the command you have to run locally to recreate the workflow - making it super easy to reproduce CI failures locally.
 
-> **Tip**
->
-> For those familiar with Conda, you are used to activating an environment. With Pixi, you can do the same by doing `pixi shell <env-name>`. For example, `pixi shell test-latest` will drop you into a shell where you can run commands such as `pytest` like normal. You can exit the shell with `exit` or `Ctrl+D`.
+```{tip}
+For those familiar with Conda, you are used to activating an environment. With Pixi, you can do the same by doing `pixi shell <env-name>`. For example, `pixi shell test-latest` will drop you into a shell where you can run commands such as `pytest` like normal. You can exit the shell with `exit` or `Ctrl+D`.
+```
 
 ### Changing code
 
@@ -127,9 +127,9 @@ From there:
 
 ### Code guidelines
 
-> **Note**
->
-> These guidelines are here to promote Python best practices, as well as standardise the Parcels code. If you're not sure what some of these guidelines mean, don't worry! Your contribution is still appreciated. When you create your pull request, maintainers can modify your code to comply with these guidelines.
+```{note}
+These guidelines are here to promote Python best practices, as well as standardise the Parcels code. If you're not sure what some of these guidelines mean, don't worry! Your contribution is still appreciated. When you create your pull request, maintainers can modify your code to comply with these guidelines.
+```
 
 - Write clear commit messages that explain the changes you've made.
 - Include tests for any new code you write. Tests are implemented using pytest and are located in the `tests` directory.

docs/community/index.md

@@ -0,0 +1,21 @@
+# Community
+
+These sections contain documentation relevant to the Parcels community.
+See the sections in the primary sidebar and below to explore.
+
+```{toctree}
+:caption: User documentation
+:maxdepth: 1
+
+contributing
+Versioning Policy <policies>
+Release Notes <https://github.com/OceanParcels/Parcels/releases>
+Parcels v4.0 Migration Guide <v4-migration>
+```
+
+```{toctree}
+:caption: Maintainer documentation
+:maxdepth: 1
+
+maintainer
+```

docs/community/index.rst

@@ -14,12 +14,8 @@
 import datetime
 import inspect
 import os
-import re
-import shutil
 import sys
-import tempfile
 import warnings
-from pathlib import Path
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -51,8 +47,7 @@
 
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
-# source_suffix = ['.rst', '.md']
-source_suffix = ".rst"
+source_suffix = [".rst", ".md"]
 
 # The encoding of source files.
 # source_encoding = 'utf-8-sig'
@@ -219,33 +214,6 @@
 }
 
 
-# Copy code examples to download directory
-downloads_folder = Path("_downloads")
-downloads_folder.mkdir(exist_ok=True)
-
-
-def make_filename_safe(filename: str, safe_char: str = "_") -> str:
-    """Make a filename safe for saving to disk."""
-    # Replace any characters that are not allowed in a filename with the safe character
-    safe_filename = re.sub(r'[\\/:*?"<>|]', safe_char, filename)
-    return safe_filename
-
-
-with tempfile.TemporaryDirectory() as temp_dir:
-    temp_dir = Path(temp_dir)
-
-    # Copy examples folder to temp directory (with a folder name matching parcels version)
-    examples_folder = temp_dir / make_filename_safe(f"parcels_tutorials ({version})")
-    shutil.copytree("examples", examples_folder)
-
-    # Zip contents of temp directory and save to _downloads folder
-    shutil.make_archive(
-        "_downloads/parcels_tutorials",
-        "zip",
-        temp_dir,
-    )
-
-
 # based on pandas doc/source/conf.py
 def linkcode_resolve(domain, info):
     """Determine the URL corresponding to Python object."""
@@ -384,6 +352,20 @@ def linkcode_resolve(domain, info):
 nbsphinx_execute = "never"
 # -- Options for LaTeX output ---------------------------------------------
 
+BRANCH = (
+    os.environ.get("READTHEDOCS_GIT_IDENTIFIER")  # ReadTheDocs
+    or "main"  # fallback
+)
+
+nbsphinx_prolog = f"""
+.. raw:: html
+
+    Run this notebook in the cloud <a href="https://mybinder.org/v2/gh/OceanParcels/Parcels/{BRANCH}?urlpath=lab/tree/docs/{{{{  env.doc2path(env.docname, base=None)  }}}}" target="_blank"><img alt="Binder badge" src="https://mybinder.org/badge_logo.svg"></a>
+    , or view it <a href="https://github.com/OceanParcels/Parcels/blob/{BRANCH}/docs/{{{{  env.doc2path(env.docname, base=None)  }}}}" target="_blank">on GitHub</a>. Notebook version corresponds with {BRANCH}.
+
+    <p style="margin-bottom: 30px"></p>
+"""
+
 latex_elements = {
     # The paper size ('letterpaper' or 'a4paper').
     # 'papersize': 'letterpaper',

docs/conf.py

@@ -0,0 +1,71 @@
+# Python Example Scripts
+
+## example_brownian.py
+
+```{literalinclude} ../examples/example_brownian.py
+:language: python
+:linenos:
+```
+
+## example_decaying_moving_eddy.py
+
+```{literalinclude} ../examples/example_decaying_moving_eddy.py
+:language: python
+:linenos:
+```
+
+## example_globcurrent.py
+
+```{literalinclude} ../examples/example_globcurrent.py
+:language: python
+:linenos:
+```
+
+## example_mitgcm.py
+
+```{literalinclude} ../examples/example_mitgcm.py
+:language: python
+:linenos:
+```
+
+## example_moving_eddies.py
+
+```{literalinclude} ../examples/example_moving_eddies.py
+:language: python
+:linenos:
+```
+
+## example_nemo_curvilinear.py
+
+```{literalinclude} ../examples/example_nemo_curvilinear.py
+:language: python
+:linenos:
+```
+
+## example_ofam.py
+
+```{literalinclude} ../examples/example_ofam.py
+:language: python
+:linenos:
+```
+
+## example_peninsula.py
+
+```{literalinclude} ../examples/example_peninsula.py
+:language: python
+:linenos:
+```
+
+## example_radial_rotation.py
+
+```{literalinclude} ../examples/example_radial_rotation.py
+:language: python
+:linenos:
+```
+
+## example_stommel.py
+
+```{literalinclude} ../examples/example_stommel.py
+:language: python
+:linenos:
+```