Merge branch 'main' into zarr_pin

tasansal · web-flow · commit f450a0cd09ba · 2025-04-30T09:07:40.000-05:00
diff --git a/.editorconfig b/.editorconfig
@@ -0,0 +1,15 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.{py,toml}]
+indent_style = space
+indent_size = 4
+
+[*.{yml,yaml,json}]
+indent_style = space
+indent_size = 2
diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -1,8 +1,8 @@
 version: 2
 build:
-  os: ubuntu-20.04
+  os: ubuntu-22.04
   tools:
-    python: "3.11"
+    python: "3.13"
 sphinx:
   configuration: docs/conf.py
 formats: all
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -37,7 +37,7 @@ Request features on the [Issue Tracker].
 
 ## How to set up your development environment
 
-You need Python 3.10+ and the following tools:
+You need Python 3.11+ and the following tools:
 
 - [uv]
 - [Nox]
@@ -106,7 +106,7 @@ Open a [pull request] to submit changes to this project.
 Your pull request needs to meet the following guidelines for acceptance:
 
 - The Nox test suite must pass without errors and warnings.
-- Include unit tests. This project maintains 100% code coverage.
+- Include unit tests. This project currently maintains 90%+ code coverage.
 - If your changes add functionality, update the documentation accordingly.
 
 Feel free to submit early, though—we can always iterate on this.
diff --git a/docs/api_reference.md b/docs/api_reference.md
@@ -1,4 +1,4 @@
-# Reference
+# API Reference
 
 ## Readers / Writers
 
diff --git a/docs/cli_usage.md b/docs/cli_usage.md
@@ -1,4 +1,4 @@
-# Usage
+# CLI Usage
 
 ## Ingestion and Export
 
@@ -68,11 +68,11 @@ Credentials can be automatically fetched from pre-authenticated AWS CLI.
 See [here](https://s3fs.readthedocs.io/en/latest/index.html#credentials) for the order `s3fs`
 checks them. If it is not pre-authenticated, you need to pass `--storage-options-{input,output}`.
 
-**Prefix:**  
+**Prefix:**
 `s3://`
 
-**Storage Options:**  
-`key`: The auth key from AWS  
+**Storage Options:**
+`key`: The auth key from AWS
 `secret`: The auth secret from AWS
 
 Using UNIX:
@@ -104,10 +104,10 @@ checks them. If it is not pre-authenticated, you need to pass `--storage-options
 GCP uses [service accounts](https://cloud.google.com/iam/docs/service-accounts) to pass
 authentication information to APIs.
 
-**Prefix:**  
+**Prefix:**
 `gs://` or `gcs://`
 
-**Storage Options:**  
+**Storage Options:**
 `token`: The service account JSON value as string, or local path to JSON
 
 Using a service account:
@@ -136,11 +136,11 @@ There are various ways to authenticate with Azure Data Lake (ADL).
 See [here](https://github.com/fsspec/adlfs#details) for some details.
 If ADL is not pre-authenticated, you need to pass `--storage-options-{input,output}`.
 
-**Prefix:**  
+**Prefix:**
 `az://` or `abfs://`
 
-**Storage Options:**  
-`account_name`: Azure Data Lake storage account name  
+**Storage Options:**
+`account_name`: Azure Data Lake storage account name
 `account_key`: Azure Data Lake storage account access key
 
 ```shell
diff --git a/docs/conf.py b/docs/conf.py
@@ -1,31 +1,66 @@
 """Sphinx configuration."""
 
+# -- Project information -----------------------------------------------------
+
 project = "MDIO"
 author = "TGS"
 copyright = "2023, TGS"
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+
 extensions = [
     "sphinx.ext.autodoc",
     "sphinx.ext.napoleon",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.autosummary",
     "sphinx.ext.autosectionlabel",
     "sphinx_click",
     "sphinx_copybutton",
     "myst_nb",
+    "sphinx_design",
 ]
 
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = [
+    "_build",
+    "Thumbs.db",
+    "jupyter_execute",
+    ".DS_Store",
+    "**.ipynb_checkpoints",
+]
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "numpy": ("https://numpy.org/doc/stable/", None),
+    "zarr": ("https://zarr.readthedocs.io/en/stable/", None),
+}
+
+pygments_style = "vs"
+pygments_dark_style = "material"
+
 autodoc_typehints = "description"
 autodoc_typehints_format = "short"
 autodoc_member_order = "groupwise"
-autoclass_content = "both"
+autoclass_content = "class"
 autosectionlabel_prefix_document = True
 
 html_theme = "furo"
 
 myst_number_code_blocks = ["python"]
 myst_heading_anchors = 2
+myst_words_per_minute = 80
 myst_enable_extensions = [
+    "colon_fence",
     "linkify",
     "replacements",
     "smartquotes",
+    "attrs_inline",
 ]
 
 # sphinx-copybutton configurations
diff --git a/docs/index.md b/docs/index.md
@@ -6,24 +6,38 @@ end-before: <!-- github-only -->
 
 [apache 2.0 license]: license
 [contributor guide]: contributing
-[command-line usage]: usage
-[api reference]: reference
+[command-line usage]: cli_usage
+[api reference]: api_reference
 [installation instructions]: installation
 
 ```{toctree}
----
-hidden:
-maxdepth: 1
----
+:hidden:
+:caption: Getting Started
+
 installation
-notebooks/quickstart
-notebooks/creation
-notebooks/compression
-notebooks/rechunking
-usage
-reference
+cli_usage
+```
+
+```{toctree}
+:hidden:
+:caption: Learning and Support
+
+tutorials/index
+api_reference
+```
+
+```{toctree}
+:hidden:
+:caption: Community and Contribution
+
 contributing
 Code of Conduct <codeofconduct>
+```
+
+```{toctree}
+:hidden:
+:caption: Additional Resources
+
 License <license>
 Changelog <https://github.com/TGSAI/mdio-python/releases>
 ```
diff --git a/docs/installation.md b/docs/installation.md
@@ -1,4 +1,4 @@
-# Install Instructions
+# Installation
 
 There are different ways to install MDIO:
 
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1,6 +1,7 @@
 furo==2024.8.6
-sphinx==8.2.1
+linkify-it-py==2.0.3
+myst-nb==1.2.0
+sphinx==8.2.3
 sphinx-click==6.0.0
 sphinx-copybutton==0.5.2
-myst-nb==1.2.0
-linkify-it-py==2.0.3
+sphinx-design==0.6.1
diff --git a/docs/tutorials/compression.ipynb b/docs/tutorials/compression.ipynb
@@ -6,6 +6,13 @@
    "source": [
     "# Seismic Data Compression\n",
     "\n",
+    "```{article-info}\n",
+    ":author: Altay Sansal\n",
+    ":date: \"{sub-ref}`today`\"\n",
+    ":read-time: \"{sub-ref}`wordcount-minutes` min read\"\n",
+    ":class-container: sd-p-0 sd-outline-muted sd-rounded-3 sd-font-weight-light\n",
+    "```\n",
+    "\n",
     "In this page we will be showing compression performance of _MDIO_.\n",
     "\n",
     "For demonstration purposes, we will use one of the Volve dataset stacks.\n",
diff --git a/docs/tutorials/creation.ipynb b/docs/tutorials/creation.ipynb
@@ -8,7 +8,14 @@
     }
    },
    "source": [
-    "# Create a New MDIO File From Scratch\n",
+    "# Create an Empty MDIO\n",
+    "\n",
+    "```{article-info}\n",
+    ":author: Altay Sansal\n",
+    ":date: \"{sub-ref}`today`\"\n",
+    ":read-time: \"{sub-ref}`wordcount-minutes` min read\"\n",
+    ":class-container: sd-p-0 sd-outline-muted sd-rounded-3 sd-font-weight-light\n",
+    "```\n",
     "\n",
     "Here we will create an empty MDIO file and populate its fields.\n",
     "\n",
diff --git a/docs/tutorials/index.md b/docs/tutorials/index.md
@@ -0,0 +1,10 @@
+# Tutorials
+
+```{toctree}
+:hidden:
+
+quickstart
+creation
+compression
+rechunking
+```
diff --git a/docs/tutorials/quickstart.ipynb b/docs/tutorials/quickstart.ipynb
@@ -10,6 +10,13 @@
    "source": [
     "# Get Started in 10 Minutes\n",
     "\n",
+    "```{article-info}\n",
+    ":author: Altay Sansal\n",
+    ":date: \"{sub-ref}`today`\"\n",
+    ":read-time: \"{sub-ref}`wordcount-minutes` min read\"\n",
+    ":class-container: sd-p-0 sd-outline-muted sd-rounded-3 sd-font-weight-light\n",
+    "```\n",
+    "\n",
     "In this page we will be showing basic capabilities of MDIO.\n",
     "\n",
     "For demonstration purposes, we will download the Teapot Dome open-source dataset. The dataset details and licensing can be found at the [SEG Wiki](https://wiki.seg.org/wiki/Teapot_dome_3D_survey).\n",
@@ -118,7 +125,7 @@
     }
    },
    "source": [
-    "It only took a few seconds to ingest, since this is a very small file. \n",
+    "It only took a few seconds to ingest, since this is a very small file.\n",
     "\n",
     "However, MDIO scales up to TB (that's ~1,000 GB) sized volumes!\n",
     "\n",
@@ -413,7 +420,7 @@
     }
    },
    "source": [
-    "We can extract a dimension by name, and see its values. \n",
+    "We can extract a dimension by name, and see its values.\n",
     "\n",
     "The `Dimension` has `name` and `coords` that returns a string and a numpy array."
    ]
@@ -657,7 +664,7 @@
    "source": [
     "We can query headers for the whole dataset very quickly because they are separated from the seismic wavefield.\n",
     "\n",
-    "Let's get all the headers for X and Y coordinates in this dataset. \n",
+    "Let's get all the headers for X and Y coordinates in this dataset.\n",
     "\n",
     "As mentioned before, X Coordinates map to `inline` and Y Coordinates map to `crossline` due to non-standard Teapot data.\n",
     "\n",
@@ -854,7 +861,7 @@
    "source": [
     "## MDIO to SEG-Y Conversion\n",
     "\n",
-    "Finally, let's demonstrate going back to SEG-Y. \n",
+    "Finally, let's demonstrate going back to SEG-Y.\n",
     "\n",
     "We will use the convenient `mdio_to_segy` function and write it out as a round-trip file."
    ]
diff --git a/docs/tutorials/rechunking.ipynb b/docs/tutorials/rechunking.ipynb
@@ -7,6 +7,13 @@
    "source": [
     "# Optimizing Access Patterns\n",
     "\n",
+    "```{article-info}\n",
+    ":author: Altay Sansal\n",
+    ":date: \"{sub-ref}`today`\"\n",
+    ":read-time: \"{sub-ref}`wordcount-minutes` min read\"\n",
+    ":class-container: sd-p-0 sd-outline-muted sd-rounded-3 sd-font-weight-light\n",
+    "```\n",
+    "\n",
     "## Introduction\n",
     "\n",
     "In this page we will be showing how we can take an existing MDIO and add\n",
@@ -455,7 +462,7 @@
     "## Optimizing in Batch\n",
     "\n",
     "Now that we understand how rechunking and lossy compression works, we will demonstrate how\n",
-    "to do this in batches. \n",
+    "to do this in batches.\n",
     "\n",
     "The benefit of doing the batched processing is that the dataset gets read once. This is\n",
     "especially important if the original MDIO resides in a remote store like AWS S3, or Google\n",
diff --git a/noxfile.py b/noxfile.py
@@ -278,6 +278,7 @@ def docs_build(session: Session) -> None:
             "sphinx",
             "sphinx-click",
             "sphinx-copybutton",
+            "sphinx-design",
             "furo",
             "myst-nb",
             "linkify-it-py",
@@ -303,6 +304,7 @@ def docs(session: Session) -> None:
             "sphinx-autobuild",
             "sphinx-click",
             "sphinx-copybutton",
+            "sphinx-design",
             "furo",
             "myst-nb",
             "linkify-it-py",
diff --git a/pyproject.toml b/pyproject.toml
diff --git a/uv.lock b/uv.lock

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Reference`
	`1`	`+# API Reference`
`2`	`2`
`3`	`3`	`## Readers / Writers`
`4`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Install Instructions`
	`1`	`+# Installation`
`2`	`2`
`3`	`3`	`There are different ways to install MDIO:`
`4`	`4`