Skip to content

[v3] Binder pre amble (port of #2293) #2316

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
VeckoTheGecko merged 1 commit into from
Oct 8, 2025
Merged

[v3] Binder pre amble (port of #2293) #2316

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/community/contributing.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
~~~~~~~~~~~~~~~
Expand Down
56 changes: 19 additions & 37 deletions docs/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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'
Expand Down Expand Up @@ -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",
Expand All @@ -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."""
Expand Down Expand Up @@ -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}"
)

Expand Down Expand Up @@ -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',
Expand Down
2 changes: 1 addition & 1 deletion docs/documentation/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
Expand Down
Loading