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

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

Author: 3 people

docs/community/contributing.rst

@@ -74,7 +74,7 @@ From there:
 - create a git branch, implement, commit, and push your changes
 - `create a pull request <https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork>`_ (PR) into ``main`` of the original repo making sure to link to the issue that you are working on. Not yet finished with your feature but still want feedback on how you're going? Then mark it as "draft" and ``@ping`` a maintainer. See our `maintainer notes <maintainer.md>`_ to see our PR review workflow.
 
-If you made changes to the documentation, and want to render a local version, you can run the command ``sphinx-autobuild --ignore "*.zip" docs docs/_build`` to create a server to automatically rebuild the documentation when you make changes.
+If you made changes to the documentation, and want to render a local version, you can run the command ``sphinx-autobuild docs docs/_build`` to create a server to automatically rebuild the documentation when you make changes.
 
 Code guidelines
 ~~~~~~~~~~~~~~~

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
@@ -50,8 +46,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'
@@ -198,7 +193,7 @@
         "image_dark": "logo-horo_dia.svg",
     },
     "use_edit_page_button": True,
-    "github_url": "https://github.com/OceanParcels/parcels",
+    "github_url": "https://github.com/Parcels-code/parcels",
     "icon_links": [
         {
             "name": "Conda Forge",
@@ -210,40 +205,13 @@
 }
 
 html_context = {
-    "github_user": "OceanParcels",
+    "github_user": "Parcels-code",
     "github_repo": "parcels",
     "github_version": "main",
     "doc_path": "docs",
 }
 
 
-# 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."""
@@ -296,11 +264,11 @@ def linkcode_resolve(domain, info):
 
     if "-" in parcels.__version__:
         return (
-            f"https://github.com/OceanParcels/parcels/blob/main/parcels/{fn}{linespec}"
+            f"https://github.com/Parcels-code/parcels/blob/main/parcels/{fn}{linespec}"
         )
     else:
         return (
-            f"https://github.com/OceanParcels/parcels/blob/"
+            f"https://github.com/Parcels-code/parcels/blob/"
             f"{parcels.__version__}/parcels/{fn}{linespec}"
         )
 
@@ -382,6 +350,20 @@ def linkcode_resolve(domain, info):
 }
 # -- 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/Parcels-code/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/Parcels-code/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.rst

@@ -1,7 +1,7 @@
 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.
 
 .. warning::
    In v3.1.0 we updated kernels in the tutorials to use ``parcels.ParcelsRandom`` instead of ``from parcels import ParcelsRandom``. Due to our C-conversion code, using ``parcels.ParcelsRandom`` only works with v3.1.0+. When browsing/downloading the tutorials, it's important that you are using the documentation corresponding to the version of Parcels that you have installed. You can find which parcels version you have installed by doing ``import parcels`` followed by ``print(parcels.__version__)``. If you don't want to use the latest version of Parcels, you can browse prior versions of the documentation by using the version switcher in the bottom right of this page.