Skip to content

Commit d6384f5

Browse files
jhammandstansbynormanrzd-v-bdcherian
authored
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 <[email protected]> * 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 <[email protected]> * 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 <[email protected]> Co-authored-by: David Stansby <[email protected]> Co-authored-by: Davis Bennett <[email protected]> * 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 <[email protected]> Co-authored-by: Norman Rzepka <[email protected]> Co-authored-by: Davis Bennett <[email protected]> Co-authored-by: Deepak Cherian <[email protected]>
1 parent c070940 commit d6384f5

26 files changed

+1565
-1982
lines changed

Diff for: ‎.github/workflows/test.yml

+26-1
Original file line numberDiff line numberDiff line change
@@ -94,13 +94,38 @@ jobs:
9494
run: |
9595
hatch env run --env ${{ matrix.dependency-set }} run
9696
97+
doctests:
98+
name: doctests
99+
runs-on: ubuntu-latest
100+
steps:
101+
- uses: actions/checkout@v4
102+
with:
103+
fetch-depth: 0 # required for hatch version discovery, which is needed for numcodecs.zarr3
104+
- name: Set up Python
105+
uses: actions/setup-python@v5
106+
with:
107+
python-version: '3.13'
108+
cache: 'pip'
109+
- name: Install Hatch
110+
run: |
111+
python -m pip install --upgrade pip
112+
pip install hatch
113+
- name: Set Up Hatch Env
114+
run: |
115+
hatch env create doctest
116+
hatch env run -e doctest list-env
117+
- name: Run Tests
118+
run: |
119+
hatch env run --env doctest run
120+
97121
test-complete:
98122
name: Test complete
99123

100124
needs:
101125
[
102126
test,
103127
test-upstream-and-min-deps,
128+
doctests
104129
]
105130
if: always()
106131
runs-on: ubuntu-latest
@@ -111,4 +136,4 @@ jobs:
111136
contains(needs.*.result, 'cancelled')
112137
run: exit 1
113138
- name: Success
114-
run: echo Success!
139+
run: echo Success!

Diff for: ‎.gitignore

+3
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,9 @@ coverage.xml
5252
# Sphinx documentation
5353
docs/_build/
5454
docs/_autoapi
55+
docs/data
56+
data
57+
data.zip
5558

5659
# PyBuilder
5760
target/

Diff for: ‎data/donotdelete

-1
This file was deleted.

Diff for: ‎docs/about.rst

+24
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
About
2+
=====
3+
4+
Zarr is a format for the storage of chunked, compressed, N-dimensional arrays
5+
inspired by `HDF5 <https://www.hdfgroup.org/HDF5/>`_, `h5py
6+
<https://www.h5py.org/>`_ and `bcolz <https://bcolz.readthedocs.io/>`_.
7+
8+
These documents describe the Zarr-Python implementation. More information
9+
about the Zarr format can be found on the `main website <https://zarr.dev>`_.
10+
11+
Projects using Zarr
12+
-------------------
13+
14+
If you are using Zarr-Python, we would `love to hear about it
15+
<https://github.com/zarr-developers/community/issues/19>`_.
16+
17+
Funding
18+
-------
19+
The project is fiscally sponsored by `NumFOCUS <https://numfocus.org/>`_, a US
20+
501(c)(3) public charity, and development is supported by the
21+
`MRC Centre for Genomics and Global Health <https://www.cggh.org>`_
22+
and the `Chan Zuckerberg Initiative <https://chanzuckerberg.com/>`_.
23+
24+
.. _NumCodecs: https://numcodecs.readthedocs.io/

Diff for: ‎docs/conf.py

+2-1
Original file line numberDiff line numberDiff line change
@@ -102,7 +102,8 @@ def skip_submodules(
102102
"spec/v1": 'https://zarr-specs.readthedocs.io/en/latest/v1/v1.0.html',
103103
"spec/v2": "https://zarr-specs.readthedocs.io/en/latest/v2/v2.0.html",
104104
"spec/v3": "https://zarr-specs.readthedocs.io/en/latest/v3/core/v3.0.html",
105-
"license": "https://github.com/zarr-developers/zarr-python/blob/main/LICENSE.txt"
105+
"license": "https://github.com/zarr-developers/zarr-python/blob/main/LICENSE.txt",
106+
"tutorial": "user-guide",
106107
}
107108

108109
# The language for content autogenerated by Sphinx. Refer to documentation

Diff for: ‎docs/getting_started.rst

-18
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,6 @@
11
Getting Started
22
===============
33

4-
Zarr is a format for the storage of chunked, compressed, N-dimensional arrays
5-
inspired by `HDF5 <https://www.hdfgroup.org/HDF5/>`_, `h5py
6-
<https://www.h5py.org/>`_ and `bcolz <https://bcolz.readthedocs.io/>`_.
7-
8-
The project is fiscally sponsored by `NumFOCUS <https://numfocus.org/>`_, a US
9-
501(c)(3) public charity, and development is supported by the
10-
`MRC Centre for Genomics and Global Health <https://www.cggh.org>`_
11-
and the `Chan Zuckerberg Initiative <https://chanzuckerberg.com/>`_.
12-
13-
These documents describe the Zarr Python implementation. More information
14-
about the Zarr format can be found on the `main website <https://zarr.dev>`_.
15-
164
Highlights
175
----------
186

@@ -31,12 +19,6 @@ Feedback and bug reports are very welcome, please get in touch via
3119
the `GitHub issue tracker <https://github.com/zarr-developers/zarr-python/issues>`_. See
3220
:doc:`contributing` for further information about contributing to Zarr.
3321

34-
Projects using Zarr
35-
-------------------
36-
37-
If you are using Zarr, we would `love to hear about it
38-
<https://github.com/zarr-developers/community/issues/19>`_.
39-
4022
.. toctree::
4123
:caption: Getting Started
4224
:hidden:

Diff for: ‎docs/guide/consolidated_metadata.rst

-74
This file was deleted.

Diff for: ‎docs/guide/index.rst

-9
This file was deleted.

Diff for: ‎docs/guide/storage.rst

-101
This file was deleted.

Diff for: ‎docs/guide/whatsnew_v3.rst

-14
This file was deleted.

Diff for: ‎docs/index.rst

+7-7
Original file line numberDiff line numberDiff line change
@@ -9,8 +9,8 @@ Zarr-Python
99
:hidden:
1010

1111
getting_started
12-
tutorial
13-
guide/index
12+
about
13+
user-guide/index
1414
api/index
1515
release
1616
contributing
@@ -52,20 +52,20 @@ Zarr is a file storage format for chunked, compressed, N-dimensional arrays base
5252
.. grid-item-card::
5353
:img-top: _static/index_user_guide.svg
5454

55-
Tutorial
56-
^^^^^^^^
55+
Guide
56+
^^^^^
5757

58-
The tutorial provides working examples of Zarr classes and functions.
58+
A detailed guide for how to use Zarr-Python.
5959

6060
+++
6161

62-
.. button-ref:: tutorial
62+
.. button-ref:: user-guide
6363
:ref-type: ref
6464
:expand:
6565
:color: dark
6666
:click-parent:
6767

68-
To the Tutorial
68+
To the user guide
6969

7070
.. grid-item-card::
7171
:img-top: _static/index_api.svg

0 commit comments

Comments
 (0)