docs: split tutorial into multiple user guide sections (#2589)

* docs: split tutorial into multiple user guide sections * Apply suggestions from code review Co-authored-by: David Stansby <dstansby@gmail.com> * respond to david's review * add todos for remainig api changes * docs: add new top level about page (#2592) * docs: add new top level about page * fixup * fixup * fixup * docs: add docs on extending zarr 3 (#2597) * docs: add docs on extending zarr 3 * Apply suggestions from code review Co-authored-by: David Stansby <dstansby@gmail.com> * move note up * remove test.py (#2612) * Note that whole directories can be deleted in LocalStore (#2606) * fix: run-coverage command now tracks src directory (#2615) * fix doc build * Update docs/user-guide/extending.rst --------- Co-authored-by: Norman Rzepka <code@normanrz.com> Co-authored-by: David Stansby <dstansby@gmail.com> Co-authored-by: Davis Bennett <davis.v.bennett@gmail.com> * Use doctests for guide (#2623) * Use doctests for arrays.rst * Use doctests for attributes.rst * Use doctests for config.rst * Use doctests for consolidated metadata * Use doctests for groups.rst * Use doctests for preformance.rst * Use doctests for storage.rst * Remove ipython config for docs * Fix performance doctest output * Enable doctests * Add a doctest CI run * Remove rmtrees * Delete data dir before doctests * Fix doctests * fix doctests for arrays.rst * fix doctests for consolidated_metadata.rst * fixes for doctest * tests * debugging * debugging * debugging * debugging * debugging --------- Co-authored-by: David Stansby <dstansby@gmail.com> Co-authored-by: Norman Rzepka <code@normanrz.com> Co-authored-by: Davis Bennett <davis.v.bennett@gmail.com> Co-authored-by: Deepak Cherian <dcherian@users.noreply.github.com>
zarr-developers · Jan 3, 2025 · d6384f5 · d6384f5
1 parent c070940
commit d6384f5
Show file tree

Hide file tree

Showing 26 changed files with 1,565 additions and 1,982 deletions.
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
@@ -94,13 +94,38 @@ jobs:
       run: |
         hatch env run --env ${{ matrix.dependency-set }} run
 
+  doctests:
+    name: doctests
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0 # required for hatch version discovery, which is needed for numcodecs.zarr3
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.13'
+        cache: 'pip'
+    - name: Install Hatch
+      run: |
+        python -m pip install --upgrade pip
+        pip install hatch
+    - name: Set Up Hatch Env
+      run: |
+        hatch env create doctest
+        hatch env run -e doctest list-env
+    - name: Run Tests
+      run: |
+        hatch env run --env doctest run
+
   test-complete:
     name: Test complete
 
     needs:
       [
         test,
         test-upstream-and-min-deps,
+        doctests
       ]
     if: always()
     runs-on: ubuntu-latest
@@ -111,4 +136,4 @@ jobs:
           contains(needs.*.result, 'cancelled')
         run: exit 1
       - name: Success
-        run: echo Success!
+        run: echo Success!
diff --git a/.gitignore b/.gitignore
@@ -52,6 +52,9 @@ coverage.xml
 # Sphinx documentation
 docs/_build/
 docs/_autoapi
+docs/data
+data
+data.zip
 
 # PyBuilder
 target/

diff --git a/data/donotdelete b/data/donotdelete
diff --git a/docs/about.rst b/docs/about.rst
@@ -0,0 +1,24 @@
+About
+=====
+
+Zarr is a format for the storage of chunked, compressed, N-dimensional arrays
+inspired by `HDF5 <https://www.hdfgroup.org/HDF5/>`_, `h5py
+<https://www.h5py.org/>`_ and `bcolz <https://bcolz.readthedocs.io/>`_.
+
+These documents describe the Zarr-Python implementation. More information
+about the Zarr format can be found on the `main website <https://zarr.dev>`_.
+
+Projects using Zarr
+-------------------
+
+If you are using Zarr-Python, we would `love to hear about it
+<https://github.com/zarr-developers/community/issues/19>`_.
+
+Funding
+-------
+The project is fiscally sponsored by `NumFOCUS <https://numfocus.org/>`_, a US
+501(c)(3) public charity, and development is supported by the
+`MRC Centre for Genomics and Global Health <https://www.cggh.org>`_
+and the `Chan Zuckerberg Initiative <https://chanzuckerberg.com/>`_.
+
+.. _NumCodecs: https://numcodecs.readthedocs.io/
diff --git a/docs/conf.py b/docs/conf.py
@@ -102,7 +102,8 @@ def skip_submodules(
      "spec/v1": 'https://zarr-specs.readthedocs.io/en/latest/v1/v1.0.html',
      "spec/v2": "https://zarr-specs.readthedocs.io/en/latest/v2/v2.0.html",
      "spec/v3": "https://zarr-specs.readthedocs.io/en/latest/v3/core/v3.0.html",
-     "license": "https://github.com/zarr-developers/zarr-python/blob/main/LICENSE.txt"
+     "license": "https://github.com/zarr-developers/zarr-python/blob/main/LICENSE.txt",
+     "tutorial": "user-guide",
 }
 
 # The language for content autogenerated by Sphinx. Refer to documentation

diff --git a/docs/getting_started.rst b/docs/getting_started.rst
@@ -1,18 +1,6 @@
 Getting Started
 ===============
 
-Zarr is a format for the storage of chunked, compressed, N-dimensional arrays
-inspired by `HDF5 <https://www.hdfgroup.org/HDF5/>`_, `h5py
-<https://www.h5py.org/>`_ and `bcolz <https://bcolz.readthedocs.io/>`_.
-
-The project is fiscally sponsored by `NumFOCUS <https://numfocus.org/>`_, a US
-501(c)(3) public charity, and development is supported by the
-`MRC Centre for Genomics and Global Health <https://www.cggh.org>`_
-and the `Chan Zuckerberg Initiative <https://chanzuckerberg.com/>`_.
-
-These documents describe the Zarr Python implementation. More information
-about the Zarr format can be found on the `main website <https://zarr.dev>`_.
-
 Highlights
 ----------
 
@@ -31,12 +19,6 @@ Feedback and bug reports are very welcome, please get in touch via
 the `GitHub issue tracker <https://github.com/zarr-developers/zarr-python/issues>`_. See
 :doc:`contributing` for further information about contributing to Zarr.
 
-Projects using Zarr
--------------------
-
-If you are using Zarr, we would `love to hear about it
-<https://github.com/zarr-developers/community/issues/19>`_.
-
 .. toctree::
     :caption: Getting Started
     :hidden:

diff --git a/docs/guide/consolidated_metadata.rst b/docs/guide/consolidated_metadata.rst
diff --git a/docs/guide/index.rst b/docs/guide/index.rst
diff --git a/docs/guide/storage.rst b/docs/guide/storage.rst
diff --git a/docs/guide/whatsnew_v3.rst b/docs/guide/whatsnew_v3.rst
diff --git a/docs/index.rst b/docs/index.rst
@@ -9,8 +9,8 @@ Zarr-Python
     :hidden:
 
     getting_started
-    tutorial
-    guide/index
+    about
+    user-guide/index
     api/index
     release
     contributing
@@ -52,20 +52,20 @@ Zarr is a file storage format for chunked, compressed, N-dimensional arrays base
     .. grid-item-card::
         :img-top: _static/index_user_guide.svg
 
-        Tutorial
-        ^^^^^^^^
+       Guide
+       ^^^^^
 
-        The tutorial provides working examples of Zarr classes and functions.
+       A detailed guide for how to use Zarr-Python.
 
         +++
 
-        .. button-ref:: tutorial
+        .. button-ref:: user-guide
             :ref-type: ref
             :expand:
             :color: dark
             :click-parent:
 
-            To the Tutorial
+            To the user guide
 
     .. grid-item-card::
         :img-top: _static/index_api.svg