Add open binder and download link pre-amble (remove zip tooling) (#2293)

Co-authored-by: Nick Hodgskin <[email protected]>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: 3 people

docs/conf.py

@@ -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/documentation/index.md

@@ -1,6 +1,6 @@
 # Documentation and Tutorials
 
-Parcels has several documentation and tutorial Jupyter notebooks and scripts which go through various aspects of Parcels. Static versions of the notebooks are available below via the gallery in the site, with the interactive notebooks being available either completely online at the following [Binder link](https://mybinder.org/v2/gh/OceanParcels/parcels/main?labpath=docs%2Fexamples%2Fparcels_tutorial.ipynb). Following the gallery of notebooks is a list of scripts which provide additional examples to users. You can work with the example notebooks and scripts locally by downloading {download}`parcels_tutorials.zip </_downloads/parcels_tutorials.zip>` and running with your own Parcels installation.
+Shown below are several documentation and tutorial Jupyter notebooks and scripts which go through various aspects of Parcels.
 
 ```{nbgallery}
 :caption: Overview

docs/v4/installation.md

@@ -1,6 +1,6 @@
 # Install an alpha version of Parcels v4
 
-During development of Parcels v4, we are uploading versions of the package to an [index on prefix.dev](https://prefix.dev/channels/parcels/packages/parcels). This allows users to easily install an unreleased version without having to do a [development install](../installation.rst)! Give it a spin!
+During development of Parcels v4, we are uploading versions of the package to an [index on prefix.dev](https://prefix.dev/channels/parcels/packages/parcels). This allows users to easily install an unreleased version without having to do a [development install](../installation.md)! Give it a spin!
 
 ```{warning}
 Before installing an alpha version of Parcels, we *highly* recommend creating a new environment so that doesn't affect package versions in your current environment (which you may be using for your research).

pixi.toml

@@ -76,7 +76,7 @@ sphinxcontrib-mermaid = "*"
 
 [feature.docs.tasks]
 docs = "sphinx-build docs docs/_build"
-docs-watch = 'sphinx-autobuild --ignore "*.zip" docs docs/_build'
+docs-watch = 'sphinx-autobuild docs docs/_build'
 docs-linkcheck = "sphinx-build -b linkcheck docs/ docs/_build/linkcheck"
 
 [feature.pre-commit.dependencies]