Use markdown and Jupyter notebooks in doc pages

.codespellrc

@@ -3,3 +3,4 @@ skip = .git,*.pdf,*.svg
 # nd - for N-dimensional
 # visibles - plural variable for visible
 ignore-words-list = nd,visibles
+ignore-regex = [A-Za-z0-9+/]{100,}

.gitignore

@@ -7,10 +7,20 @@ dist/
 target/
 docs/build/
 *.DS_Store
+*Thumbs.db
 # Testing files
 .tox*
 .coverage*
 coverage.xml
 
 # Generated version file
 ome_zarr/_version.py
+
+# MyST build outputs
+_build
+
+# demo notebooks
+*.ome.zarr
+*.zarr
+*.ipynb_checkpoints
+*/jupyter_execute

.readthedocs.yml

@@ -13,7 +13,7 @@ build:
 
 # Build documentation in the docs/ directory with Sphinx
 sphinx:
-  fail_on_warning: true
+  fail_on_warning: false
   configuration: docs/source/conf.py
 
 # If using Sphinx, optionally build your docs in additional formats such as PDF
@@ -23,4 +23,6 @@ sphinx:
 # Optionally declare the Python requirements required to build your docs
 python:
   install:
-    - requirements: docs/requirements.txt
+  - requirements: docs/requirements.txt
+  - method: pip
+    path: .

docs/requirements.txt

@@ -8,3 +8,15 @@ rangehttpserver
 scipy
 scikit-image
 Deprecated
+sphinx-copybutton
+sphinx-togglebutton
+myst-nb
+sphinx-thebe
+sphinx-comments
+sphinx-design
+sphinx-book-theme
+sphinx-external-toc
+sphinx-jupyterbook-latex
+linkify-it-py
+napari
+pyqt6

docs/source/_toc.yml

@@ -0,0 +1,40 @@
+format: jb-book
+root: index
+
+options:
+  numbered: False
+
+parts:
+  - caption: Basic
+    chapters:
+    - file: basic/write_image
+    - file: basic/read_image
+    - file: basic/view_images
+    - file: basic/write_labels
+    - file: basic/cli_basics
+
+
+  - caption: Advanced
+    chapters:
+    - file: advanced/build_custom_pyramid
+    - file: advanced/write_hcs_plate
+
+  - caption: Explanation
+    chapters:
+    - file: explanation/ome_ngff_overview
+    - file: explanation/multiscale_pyramids
+    - file: explanation/zarr_concepts
+
+  - caption: API Reference
+    chapters:
+    - file: api
+      sections:
+      - file: api/writer
+      - file: api/reader
+      - file: api/io
+      - file: api/scale
+      - file: api/format
+      - file: api/cli
+      - file: api/utils
+      - file: api/csv
+      - file: api/data

docs/source/advanced/build_custom_pyramid.ipynb

@@ -0,0 +1,210 @@
+{
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "id": "95d84769",
+      "metadata": {},
+      "source": [
+        "# Customizing the pyramid\n",
+        "(advanced:pyramid)=\n",
+        "\n",
+        "\n",
+        "Multi-resolution pyramids are an integral part of ome-zarr image data\n",
+        "and enable fast rendering of large images.\n",
+        "The entrypoints to writing ome-zarr images in ome-zarr-py ({py:func}`ome_zarr.writer.write_image` and {py:func}`ome_zarr.writer.write_labels`)\n",
+        "build these pyramids under the hood as delayed dask arrays based on the settings for the scaling functions and scale factors.\n",
+        "\n",
+        "In this example, the downsampling will be applied in all spatial dimensions *except the z dimension*, which will be left at a scale factor of 1.\n",
+        "To apply equal or custom downsampling factors along all spatial dimensions, pass the scale factors as a list of dicts (see [below](#advanced:custom-downsampling-values))."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": 16,
+      "id": "642955b1",
+      "metadata": {},
+      "outputs": [
+        {
+          "data": {
+            "text/plain": [
+              "[]"
+            ]
+          },
+          "execution_count": 16,
+          "metadata": {},
+          "output_type": "execute_result"
+        }
+      ],
+      "source": [
+        "import numpy as np\n",
+        "\n",
+        "from ome_zarr.writer import write_image\n",
+        "\n",
+        "scale_factors = [2, 4, 8]\n",
+        "rng = np.random.default_rng(0)\n",
+        "data = rng.poisson(lam=10, size=(64, 64, 64)).astype(np.uint8)\n",
+        "\n",
+        "write_image(\n",
+        "    data,\n",
+        "    \"test_ngff_image.ome.zarr\",\n",
+        "    axes=\"zyx\",\n",
+        "    scale_factors=scale_factors,\n",
+        "    )"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "id": "cec0fc73",
+      "metadata": {},
+      "source": [
+        "## Custom downsampling values\n",
+        "(advanced:custom-downsampling-values)=\n",
+        "\n",
+        "To specify custom downsampling values, pass a list of dictionaries with the keys being the names of the axes to the writer function like in the following example.\n",
+        "This will apply equal downsampling factors along all present axes (`zyx` in this case):"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": 17,
+      "id": "60dcd278",
+      "metadata": {},
+      "outputs": [
+        {
+          "data": {
+            "text/plain": [
+              "[]"
+            ]
+          },
+          "execution_count": 17,
+          "metadata": {},
+          "output_type": "execute_result"
+        }
+      ],
+      "source": [
+        "scale_factors = [\n",
+        "    {\"z\": 2,\"x\": 2, \"y\": 2},\n",
+        "    {\"z\": 4,\"x\": 4, \"y\": 4},\n",
+        "    {\"z\": 8,\"x\": 8, \"y\": 8},\n",
+        "]\n",
+        "\n",
+        "write_image(\n",
+        "    data,\n",
+        "    \"test_ngff_image_custom_scale.ome.zarr\",\n",
+        "    axes=\"zyx\",\n",
+        "    scale_factors=scale_factors,\n",
+        "    )"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "id": "6b276be7",
+      "metadata": {},
+      "source": [
+        "## Custom downsampling functions\n",
+        "\n",
+        "ome-zarr-py provides multiple methods for downsampling, which can be found in the {py:class}`ome_zarr.scale.Methods` class:"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": 18,
+      "id": "877ab60d",
+      "metadata": {},
+      "outputs": [
+        {
+          "name": "stdout",
+          "output_type": "stream",
+          "text": [
+            "['resize', 'nearest', 'local_mean', 'zoom']\n"
+          ]
+        }
+      ],
+      "source": [
+        "from ome_zarr.scale import Methods\n",
+        "\n",
+        "print([m.value for m in Methods])"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "id": "9a086164",
+      "metadata": {},
+      "source": [
+        "You can use one of these functions for downsampling by passing the method name as a string to the writer function, e.g. `method=\"local_mean\"` or `method=\"resize\"`, i.e.:"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": 19,
+      "id": "859ca482",
+      "metadata": {},
+      "outputs": [
+        {
+          "data": {
+            "text/plain": [
+              "[]"
+            ]
+          },
+          "execution_count": 19,
+          "metadata": {},
+          "output_type": "execute_result"
+        }
+      ],
+      "source": [
+        "write_image(\n",
+        "    data,\n",
+        "    \"test_ngff_image_custom_method.ome.zarr\",\n",
+        "    axes=\"zyx\",\n",
+        "    scale_factors=scale_factors,\n",
+        "    method=\"nearest\"\n",
+        ")\n"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "id": "893a1b3b",
+      "metadata": {},
+      "source": [
+        "```{warning}\n",
+        "\n",
+        "The choice of the correct downsampling function is typically of secondary importance,\n",
+        "*unless* your data specifically requires a certain method.\n",
+        "\n",
+        "For instance, when writing categorical data (i.e., segmentations or generally labels),\n",
+        "you will want to use a method that preserves the label values, such as {py:func}`ome_zarr.scale.Methods.NEAREST`.\n",
+        "\n",
+        "See also section on [writing labels](basic:labels)\n",
+        "\n",
+        "```"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "id": "fbbeecf3",
+      "metadata": {},
+      "source": []
+    }
+  ],
+  "metadata": {
+    "kernelspec": {
+      "display_name": "ngff-spec",
+      "language": "python",
+      "name": "python3"
+    },
+    "language_info": {
+      "codemirror_mode": {
+        "name": "ipython",
+        "version": 3
+      },
+      "file_extension": ".py",
+      "mimetype": "text/x-python",
+      "name": "python",
+      "nbconvert_exporter": "python",
+      "pygments_lexer": "ipython3",
+      "version": "3.12.12"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 5
+}