diff --git a/docs/conf.py b/docs/conf.py index e45d42189..8a8ee89bf 100755 --- a/docs/conf.py +++ b/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 Binder badge + , or view it on GitHub. Notebook version corresponds with {BRANCH}. + +

+""" + latex_elements = { # The paper size ('letterpaper' or 'a4paper'). # 'papersize': 'letterpaper', diff --git a/docs/documentation/index.md b/docs/documentation/index.md index 678b80c40..08c460c88 100644 --- a/docs/documentation/index.md +++ b/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 ` 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 diff --git a/docs/v4/installation.md b/docs/v4/installation.md index b7756f225..8928ffd5d 100644 --- a/docs/v4/installation.md +++ b/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). diff --git a/pixi.toml b/pixi.toml index 58f5a6a5e..792479e08 100644 --- a/pixi.toml +++ b/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]