xarray-binfile 0.1.0b0__tar.gz → 0.1.0b2__tar.gz

{xarray_binfile-0.1.0b0 → xarray_binfile-0.1.0b2}/.github/dependabot.yml

@@ -8,11 +8,20 @@ updates:
       actions:
         patterns:
           - "*"
+    cooldown:
+      default-days: 7
   - package-ecosystem: "pip"
     directory: "/"
     schedule:
       interval: "weekly"
+    ignore:
+      - dependency-name: "jupyter-book"
+        update-types: ["version-update:semver-major"]
+      - dependency-name: "sphinx"
+        update-types: ["version-update:semver-major"]
     groups:
       pip-dependencies:
         patterns:
           - "*"
+    cooldown:
+      default-days: 7

{xarray_binfile-0.1.0b0 → xarray_binfile-0.1.0b2}/.github/workflows/check-links.yaml

@@ -17,7 +17,7 @@ jobs:
   check-links:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
           persist-credentials: false
       - uses: gaurav-nelson/github-action-markdown-link-check@3c3b66f1f7d0900e37b71eca45b63ea9eedfce31 # 1.0.17

{xarray_binfile-0.1.0b0 → xarray_binfile-0.1.0b2}/.github/workflows/ci.yaml

@@ -28,17 +28,25 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest, windows-latest, macos-latest]
-        python-version: ["3.10", "3.11", "3.12", "3.13"]
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14", "3.15"]
+        exclude:
+          - os: windows-latest
+            python-version: "3.15"
+          - os: macos-latest
+            python-version: "3.15"
     runs-on: ${{ matrix.os }}
+    # Python 3.15 is still a release candidate, so keep a single advisory job
+    continue-on-error: ${{ matrix.python-version == '3.15' }}
     steps:
-      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
           persist-credentials: false
 
       - name: Set up Python
-        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
         with:
           python-version: ${{ matrix.python-version }}
+          allow-prereleases: true
 
       - name: Install Hatch
         uses: pypa/hatch@257e27e51a6a5616ed08a39a408a21c35c9931bc
@@ -48,7 +56,7 @@ jobs:
           hatch run +py=${{ matrix.python-version }} test:extended --cov-report=xml:coverage.${{ matrix.os }}.${{ matrix.python-version }}.xml
 
       - name: Upload coverage data
-        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: coverage-${{ matrix.os }}-${{ matrix.python-version }}
           path: coverage.*.xml
@@ -57,21 +65,21 @@ jobs:
     needs: test
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
           persist-credentials: false
-      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
         with:
           python-version: "3.12"
       - name: Install Hatch
         uses: pypa/hatch@257e27e51a6a5616ed08a39a408a21c35c9931bc
       - name: Build package
         run: hatch build
-      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           path: dist/*.tar.gz
           name: built-sdist
-      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           path: dist/*.whl
           name: built-bdist
@@ -83,19 +91,19 @@ jobs:
     permissions:
       contents: read
     steps:
-      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
           persist-credentials: false
           fetch-depth: 0 # Shallow clones should be disabled for a better relevancy of analysis
 
       - name: Download coverage data
-        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
         with:
           pattern: coverage-*
           merge-multiple: true
 
       - name: SonarQube Scan
-        uses: SonarSource/sonarqube-scan-action@2500896589ef8f7247069a56136f8dc177c27ccf # v5.2.0
+        uses: SonarSource/sonarqube-scan-action@713881670b6b3676cda39549040e2d88c70d582e # v8.2.0
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
@@ -103,7 +111,7 @@ jobs:
           args: >
             -Dsonar.organization=fschuch
             -Dsonar.projectKey=fschuch_xarray-binfile
-            -Dsonar.python.version=3.9,3.10,3.11,3.12,3.13
+            -Dsonar.python.version=3.10,3.11,3.12,3.13,3.14,3.15
             -Dsonar.sources=src/xarray_binfile
             -Dsonar.tests=tests
             -Dsonar.python.coverage.reportPaths=coverage.*.xml
@@ -121,14 +129,14 @@ jobs:
     permissions:
       id-token: write # IMPORTANT: this permission is mandatory for trusted publishing
     steps:
-      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
         with:
           name: built-sdist
           path: dist
-      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
         with:
           name: built-bdist
           path: dist
 
       - name: Publish package distributions to PyPI
-        uses: pypa/gh-action-pypi-publish@76f52bc884231f62b9a034ebfe128415bbaabdfc # v1.12.4
+        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # v1.14.0

{xarray_binfile-0.1.0b0 → xarray_binfile-0.1.0b2}/.github/workflows/docs.yaml

@@ -24,24 +24,27 @@ jobs:
     permissions:
       contents: read
     steps:
-      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
           persist-credentials: false
 
       - name: Set up Python
-        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
         with:
           python-version: "3.13"
 
       - name: Install Hatch
         uses: pypa/hatch@257e27e51a6a5616ed08a39a408a21c35c9931bc
 
+      - name: Install Graphviz
+        run: sudo apt-get update && sudo apt-get install --yes graphviz
+
       - name: Build the book
         env:
           SPHINX_GITHUB_CHANGELOG_TOKEN: ${{ github.token }}
         run: hatch run docs:build
 
-      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           path: build/
           name: documentation
@@ -53,14 +56,14 @@ jobs:
     permissions:
       contents: write
     steps:
-      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
         with:
           path: build/
           name: documentation
 
       # Push the book's HTML to github-pages
       - name: GitHub Pages action
-        uses: peaceiris/actions-gh-pages@4f9cc6602d3f66b9c108549d475ec49e8ef4d45e # v4.0.0
+        uses: peaceiris/actions-gh-pages@84c30a85c19949d7eee79c4ff27748b70285e453 # v4.1.0
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           publish_dir: build/_build/html

{xarray_binfile-0.1.0b0 → xarray_binfile-0.1.0b2}/.gitignore

@@ -48,6 +48,7 @@ coverage.xml
 *.cover
 *.py,cover
 .hypothesis/
+.benchmarks/
 .pytest_cache/
 cover/
 
@@ -72,6 +73,9 @@ instance/
 docs/_build/
 docs/conf.py
 
+# Dask task-graph artifact written by .visualize() during notebook execution
+docs/tutorials/mydask.*
+
 # PyBuilder
 .pybuilder/
 target/

{xarray_binfile-0.1.0b0 → xarray_binfile-0.1.0b2}/.pre-commit-config.yaml

@@ -2,7 +2,7 @@ default_language_version:
   python: python
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v5.0.0
+    rev: v6.0.0
     hooks:
       - id: check-added-large-files
       - id: check-case-conflict
@@ -17,7 +17,7 @@ repos:
       - id: mixed-line-ending
       - id: trailing-whitespace
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.12.3
+    rev: v0.15.20
     hooks:
       # Run the linter.
       - id: ruff
@@ -27,28 +27,28 @@ repos:
       - id: ruff-format
         types_or: [python, pyi, jupyter]
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.16.1
+    rev: v2.1.0
     hooks:
       - id: mypy
         exclude: docs/conf.py
   - repo: https://github.com/codespell-project/codespell
-    rev: v2.4.1
+    rev: v2.4.2
     hooks:
       - id: codespell
         additional_dependencies:
           - tomli
   - repo: https://github.com/executablebooks/mdformat
-    rev: 0.7.22
+    rev: 1.0.0
     hooks:
       - id: mdformat
         additional_dependencies:
           [mdformat-gfm, mdformat-frontmatter, mdformat-footnote]
   - repo: https://github.com/kynan/nbstripout
-    rev: 0.8.1
+    rev: 0.9.1
     hooks:
       - id: nbstripout
   - repo: https://github.com/woodruffw/zizmor-pre-commit
-    rev: v1.11.0
+    rev: v1.26.1
     hooks:
       - id: zizmor
 

{xarray_binfile-0.1.0b0 → xarray_binfile-0.1.0b2}/.vscode/settings.json

@@ -23,5 +23,6 @@
     },
     "cSpell.enabled": true,
     "cSpell.language": "en",
-    "python.envFile": "${workspaceFolder}/.venv/xarray-binfile"
+    "python.envFile": "${workspaceFolder}/.venv/xarray-binfile",
+    "python.testing.pytestPath": "${workspaceFolder}/.venv/xarray-binfile/bin/pytest"
 }

{xarray_binfile-0.1.0b0 → xarray_binfile-0.1.0b2}/PKG-INFO

@@ -1,17 +1,16 @@
 Metadata-Version: 2.4
 Name: xarray-binfile
-Version: 0.1.0b0
+Version: 0.1.0b2
 Summary: Read and write raw binary files using the familiar interface from the Xarray library
 Project-URL: Source, https://github.com/fschuch/xarray-binfile
 Project-URL: Tracker, https://github.com/fschuch/xarray-binfile/issues
-Project-URL: Changelog, https://fschuch.github.io/xarray-binfile/references/what-is-new.html
-Project-URL: Documentation, https://fschuch.github.io/xarray-binfile/
+Project-URL: Changelog, https://docs.fschuch.com/xarray-binfile/references/what-is-new.html
+Project-URL: Documentation, https://docs.fschuch.com/xarray-binfile/
 Author-email: fschuch <me@fschuch.com>
 License-Expression: MIT
 License-File: LICENSE
-Classifier: Development Status :: 4 - Beta
+Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
@@ -19,14 +18,20 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
 Requires-Python: >=3.10
 Requires-Dist: dask>=2024.0.0
+Requires-Dist: numpy>=1.24
 Requires-Dist: xarray>=2024.1.0
+Provides-Extra: benchmarks
+Requires-Dist: pytest-memray>=1.7.0; (sys_platform != 'win32') and extra == 'benchmarks'
 Provides-Extra: docs
-Requires-Dist: docutils==0.21.2; extra == 'docs'
+Requires-Dist: graphviz>=0.20.3; extra == 'docs'
 Requires-Dist: jupyter-book==1.0.4.post1; extra == 'docs'
+Requires-Dist: matplotlib>=3.9.0; extra == 'docs'
 Requires-Dist: sphinx-autobuild==2024.10.3; extra == 'docs'
-Requires-Dist: sphinx-github-changelog==1.7.1; extra == 'docs'
+Requires-Dist: sphinx-github-changelog==1.7.2; extra == 'docs'
 Requires-Dist: sphinx==7.4.7; extra == 'docs'
 Provides-Extra: tests
 Requires-Dist: coverage[toml]>=7.5.3; extra == 'tests'
@@ -34,18 +39,17 @@ Requires-Dist: hypothesis>=6.130.4; extra == 'tests'
 Requires-Dist: pre-commit>=3.5.0; extra == 'tests'
 Requires-Dist: pytest-benchmark>=5.1.0; extra == 'tests'
 Requires-Dist: pytest-cov>=5.0.0; extra == 'tests'
-Requires-Dist: pytest-memray>=1.7.0; (sys_platform != 'win32') and extra == 'tests'
 Requires-Dist: pytest>=8.2.2; extra == 'tests'
 Provides-Extra: tests-extra
-Requires-Dist: pytest-randomly==3.16.0; extra == 'tests-extra'
-Requires-Dist: pytest-rerunfailures==15.1; extra == 'tests-extra'
+Requires-Dist: pytest-randomly==4.1.0; extra == 'tests-extra'
+Requires-Dist: pytest-rerunfailures==16.3; extra == 'tests-extra'
 Requires-Dist: pytest-xdist==3.8.0; extra == 'tests-extra'
 Description-Content-Type: text/markdown
 
 # Xarray-binfile
 
 <p align="center">
-<a href="https://github.com/fschuch/xarray-binfile"><img src="https://raw.githubusercontent.com/fschuch/xarray-binfile/refs/heads/main/docs/logo.png" alt="Wizard template logo" width="320"></a>
+<a href="https://github.com/fschuch/xarray-binfile"><img src="https://raw.githubusercontent.com/fschuch/xarray-binfile/refs/heads/main/docs/logo.png" alt="Xarray-binfile logo" width="320"></a>
 </p>
 <p align="center">
     <em>Custom Xarray file engine to handle raw binary files</em>
@@ -61,8 +65,8 @@ ______________________________________________________________________
   [![Coverage](https://sonarcloud.io/api/project_badges/measure?project=fschuch_xarray-binfile&metric=coverage)](https://sonarcloud.io/summary/new_code?id=fschuch_xarray-binfile)
   [![CodeFactor](https://www.codefactor.io/repository/github/fschuch/xarray-binfile/badge)](https://www.codefactor.io/repository/github/fschuch/xarray-binfile)
 
-<!-- - Docs:
-  [![Docs](https://github.com/fschuch/xarray-binfile/actions/workflows/docs.yaml/badge.svg?branch=main)](https://docs.fschuch.com/xarray-binfile) -->
+- Docs:
+  [![Docs](https://github.com/fschuch/xarray-binfile/actions/workflows/docs.yaml/badge.svg?branch=main)](https://docs.fschuch.com/xarray-binfile)
 
 - Package:
   [![PyPI - Version](https://img.shields.io/pypi/v/xarray-binfile.svg?logo=pypi&label=PyPI)](https://pypi.org/project/xarray-binfile/)
@@ -80,7 +84,16 @@ ______________________________________________________________________
 
 ## Overview
 
-Xarray-binfile is a Python package designed to extend the capabilities of Xarray, a powerful library for working with labeled multi-dimensional arrays. This package provides a custom file engine specifically for reading and writing raw binary files, enabling users to leverage Xarray's data structures while working with binary data formats.
+Xarray-binfile is a Python package that integrates raw binary files with xarray. You provide the metadata that describes each binary file, and the package exposes those files through xarray datasets and data arrays with optional lazy chunking through Dask.
+
+The package was first designed around binary outputs from the Fortran framework [2DECOMP&FFT](https://github.com/2decomp-fft/2decomp-fft) and the CFD solver [Xcompact3d](https://github.com/xcompact3d/Incompact3d), which is built on top of it. It is not limited to those ecosystems and can be used with any raw binary convention once the corresponding metadata mapping is provided.
+
+It is aimed at workflows where raw binary files are part of an existing convention, such as simulation outputs or NumPy `.tofile()` dumps. Once opened, the data can be indexed, reduced, plotted, and computed with the usual xarray and Dask APIs.
+
+See the documentation for end-to-end examples covering lazy loading, Dask-backed computations, task-graph visualization, writing derived results back to `.bin` files, parallel and larger-than-memory workflows, benchmarking on your own data, batch dtype conversion, probe time-series export to CSV, and quick matplotlib plots.
+
+> [!CAUTION]
+> Raw binary files are machine- and convention-dependent. Differences such as little-endian vs big-endian byte order, word size, record layout, and memory ordering can change how bytes should be interpreted. Always verify dtype and endianness when sharing files across machines or toolchains.
 
 ## Copyright and License
 

{xarray_binfile-0.1.0b0 → xarray_binfile-0.1.0b2}/README.md

@@ -1,7 +1,7 @@
 # Xarray-binfile
 
 <p align="center">
-<a href="https://github.com/fschuch/xarray-binfile"><img src="https://raw.githubusercontent.com/fschuch/xarray-binfile/refs/heads/main/docs/logo.png" alt="Wizard template logo" width="320"></a>
+<a href="https://github.com/fschuch/xarray-binfile"><img src="https://raw.githubusercontent.com/fschuch/xarray-binfile/refs/heads/main/docs/logo.png" alt="Xarray-binfile logo" width="320"></a>
 </p>
 <p align="center">
     <em>Custom Xarray file engine to handle raw binary files</em>
@@ -17,8 +17,8 @@ ______________________________________________________________________
   [![Coverage](https://sonarcloud.io/api/project_badges/measure?project=fschuch_xarray-binfile&metric=coverage)](https://sonarcloud.io/summary/new_code?id=fschuch_xarray-binfile)
   [![CodeFactor](https://www.codefactor.io/repository/github/fschuch/xarray-binfile/badge)](https://www.codefactor.io/repository/github/fschuch/xarray-binfile)
 
-<!-- - Docs:
-  [![Docs](https://github.com/fschuch/xarray-binfile/actions/workflows/docs.yaml/badge.svg?branch=main)](https://docs.fschuch.com/xarray-binfile) -->
+- Docs:
+  [![Docs](https://github.com/fschuch/xarray-binfile/actions/workflows/docs.yaml/badge.svg?branch=main)](https://docs.fschuch.com/xarray-binfile)
 
 - Package:
   [![PyPI - Version](https://img.shields.io/pypi/v/xarray-binfile.svg?logo=pypi&label=PyPI)](https://pypi.org/project/xarray-binfile/)
@@ -36,7 +36,16 @@ ______________________________________________________________________
 
 ## Overview
 
-Xarray-binfile is a Python package designed to extend the capabilities of Xarray, a powerful library for working with labeled multi-dimensional arrays. This package provides a custom file engine specifically for reading and writing raw binary files, enabling users to leverage Xarray's data structures while working with binary data formats.
+Xarray-binfile is a Python package that integrates raw binary files with xarray. You provide the metadata that describes each binary file, and the package exposes those files through xarray datasets and data arrays with optional lazy chunking through Dask.
+
+The package was first designed around binary outputs from the Fortran framework [2DECOMP&FFT](https://github.com/2decomp-fft/2decomp-fft) and the CFD solver [Xcompact3d](https://github.com/xcompact3d/Incompact3d), which is built on top of it. It is not limited to those ecosystems and can be used with any raw binary convention once the corresponding metadata mapping is provided.
+
+It is aimed at workflows where raw binary files are part of an existing convention, such as simulation outputs or NumPy `.tofile()` dumps. Once opened, the data can be indexed, reduced, plotted, and computed with the usual xarray and Dask APIs.
+
+See the documentation for end-to-end examples covering lazy loading, Dask-backed computations, task-graph visualization, writing derived results back to `.bin` files, parallel and larger-than-memory workflows, benchmarking on your own data, batch dtype conversion, probe time-series export to CSV, and quick matplotlib plots.
+
+> [!CAUTION]
+> Raw binary files are machine- and convention-dependent. Differences such as little-endian vs big-endian byte order, word size, record layout, and memory ordering can change how bytes should be interpreted. Always verify dtype and endianness when sharing files across machines or toolchains.
 
 ## Copyright and License
 

{xarray_binfile-0.1.0b0 → xarray_binfile-0.1.0b2}/docs/_config.yml

@@ -1,10 +1,10 @@
 # Book settings
 # Learn more at https://jupyterbook.org/customize/config.html
 
-title: The Wizard Template for Python Projects
+title: Xarray-binfile
 author: Felipe N. Schuch
 copyright: "2025"
-description: A general-purpose template that aims to provide a magical start to any Python project
+description: Read and write raw binary files using the familiar interface from the Xarray library
 logo: logo.png
 
 # Force re-execution of notebooks on each build.
@@ -37,6 +37,7 @@ html:
   use_edit_page_button: true
   use_issues_button: true
   use_repository_button: true
+  announcement: Found a problem with a file layout or metadata convention? Please report it on GitHub.
 
 sphinx:
   extra_extensions:
@@ -48,14 +49,31 @@ sphinx:
     #https://github.com/executablebooks/jupyter-book/issues/1950#issuecomment-1454801479
     suppress_warnings: ["mystnb.unknown_mime_type"]
 
+    # allow_errors: false only reports failed cells as warnings; this makes
+    # a notebook execution error abort the build with a non-zero exit code
+    nb_execution_raise_on_error: true
+
     intersphinx_mapping:
       python:
         - "https://docs.python.org/3"
         - null
+      numpy:
+        - "https://numpy.org/doc/stable/"
+        - null
+      xarray:
+        - "https://docs.xarray.dev/en/stable/"
+        - null
+      dask:
+        - "https://docs.dask.org/en/stable/"
+        - null
 
     napoleon_include_special_with_doc: true
     napoleon_google_docstring: true
     napoleon_numpy_docstring: false
+    # Render "Attributes:" sections as :ivar: fields instead of .. attribute::
+    # directives, so they do not clash with the members autodoc documents
+    # (which raises "duplicate object description" warnings otherwise)
+    napoleon_use_ivar: true
 
     html_theme_options:
       icon_links:
@@ -67,7 +85,3 @@ sphinx:
           url: "https://github.com/fschuch/xarray-binfile/releases"
           icon: "https://img.shields.io/github/v/release/fschuch/xarray-binfile?style=social"
           type: "url"
-        - name: "Use this Template"
-          url: "https://github.com/new?template_name=xarray-binfile&template_owner=fschuch"
-          icon: "https://img.shields.io/badge/Use_this_Template-%23447CAA?style=social&logo=github"
-          type: "url"

xarray_binfile-0.1.0b2/docs/_toc.yml

@@ -0,0 +1,24 @@
+# Table of contents
+# Learn more at https://jupyterbook.org/customize/toc.html
+
+format: jb-book
+root: intro
+parts:
+  - caption: Getting Started
+    chapters:
+      - file: getting-started/about.md
+      - file: getting-started/installation.md
+  - caption: Usage
+    chapters:
+      - file: usage/spec-getter-protocols.md
+      - file: tutorials/read.ipynb
+      - file: tutorials/write.ipynb
+      - file: tutorials/parallel-and-larger-than-memory.ipynb
+      - file: tutorials/benchmarking.ipynb
+      - file: tutorials/examples.ipynb
+  - caption: References
+    chapters:
+      - file: references/further-reading.md
+      - file: references/api-reference.rst
+      - file: references/how-to-contribute.md
+      - file: references/what-is-new.md

xarray_binfile-0.1.0b2/docs/getting-started/about.md

@@ -0,0 +1,29 @@
+# About
+
+Xarray-binfile is an xarray backend for raw binary files. It is designed for workflows where the bytes on disk are simple and efficient, but the metadata needed to interpret them lives outside the file itself.
+
+The first target use case was binary outputs produced in workflows around the Fortran framework [2DECOMP&FFT](https://github.com/2decomp-fft/2decomp-fft) and the CFD solver [Xcompact3d](https://github.com/xcompact3d/Incompact3d). Even so, the backend is not tied to those projects and can be adapted to any compatible raw binary naming and metadata convention.
+
+Typical examples include:
+
+- output from Fortran or C/C++ simulation codes
+- binary dumps created with `numpy.ndarray.tofile`
+- one-file-per-variable or one-file-per-timestep layouts from CFD and scientific computing pipelines
+
+The package integrates with xarray in two directions:
+
+- reading through `xr.open_dataset(..., engine="binfile")` and `xr.open_mfdataset(..., engine="binfile")`
+- writing through the `.binary_engine.to_file(...)` accessor on `xarray.DataArray` and `xarray.Dataset`
+
+The read engine is registered automatically with xarray as a plugin entry point. The write accessors become available as soon as `xarray_binfile` (or any of its modules) is imported.
+
+Xarray-binfile focuses on translating between raw binary files and xarray objects. Once the data is open, standard xarray and Dask operations apply:
+
+- coordinate-based indexing with `.sel(...)`
+- positional indexing with `.isel(...)`
+- grouped and labeled reductions such as `.mean(...)`
+- lazy loading and parallel execution with Dask until `.compute()` or `.load()` is called
+
+The tutorials in this documentation show the backend in that larger ecosystem instead of treating it as a standalone file reader.
+
+For broader coverage of analysis, visualization, and distributed execution, see the [xarray documentation](https://docs.xarray.dev) and the [Dask documentation](https://docs.dask.org).

xarray_binfile-0.1.0b2/docs/getting-started/installation.md

@@ -0,0 +1,51 @@
+# Installation
+
+As a Python package, `xarray-binfile` can be installed with pip from PyPI or directly from GitHub. The package depends on both xarray and Dask at runtime, because its primary workflow is lazy, chunked access to raw binary datasets.
+
+You can use your preferred environment management tool, activate an existing environment, and then install the package with pip:
+
+```bash
+pip install xarray-binfile
+```
+
+The command above installs the latest release from PyPI. To reproduce an environment later, pin the exact version you need by adding a version specifier, for example `pip install "xarray-binfile==X.Y.Z"`.
+
+You can also use any dependency management tool that supports pip-style dependencies, such as Poetry, Hatch, uv, or Conda:
+
+::::{tab-set}
+
+:::{tab-item} `requirements.txt`
+
+```text
+xarray-binfile
+```
+
+:::
+
+:::{tab-item} `pyproject.toml`
+
+```toml
+[project]
+dependencies = [
+  "xarray-binfile",
+]
+```
+
+:::
+
+:::{tab-item} `environment.yml`
+
+```yaml
+name: xarray-binfile-example
+channels:
+  - conda-forge
+dependencies:
+  - python=3.12
+  - pip
+  - pip:
+      - xarray-binfile
+```
+
+:::
+
+::::