Restructure docs, clarify extension points and configs, use short ids

docs/_static/css/custom.css

@@ -15,4 +15,9 @@ footer {
 
 .sidebar-end-items {
     margin-top: 0% !important;
-}
+}
+
+/* Remove ↗ for external links in top bar menu */
+.nav-link.nav-external:after {
+    display: none;
+}

docs/conf.py

@@ -31,6 +31,7 @@
   'sphinx.ext.todo',
   'sphinxcontrib.mermaid',
   'sphinxmark',
+  'sphinx_reredirects',
 ]
 
 # Display todos by setting to True
@@ -60,12 +61,18 @@
 html_theme_options = {
   "github_url": "https://github.com/zarr-developers/zarr-specs",
   "twitter_url": "https://twitter.com/zarr_dev/",
+  "icon_links": [
+    {
+      "name": "Gitter",
+      "url": "https://gitter.im/zarr-developers/community",
+      "icon": "fa-brands fa-gitter",
+    },
+  ],
   "show_prev_next": False,
   "secondary_sidebar_items": ["page-toc"],
   "footer_items": [],  # hidden in custom css
 }
 
-
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
@@ -79,3 +86,7 @@
     # suppress "duplicate citation" warnings
     'ref.citation',
 ]
+
+redirects = {
+    "index": "specs.html",
+}

docs/index.rst

@@ -1,19 +1,15 @@
-=====================
- Zarr specifications
-=====================
+=====
+Specs
+=====
 
 A good starting point is the :ref:`zarr-core-specification-v3.0`.
 
 .. toctree::
-   :glob:
-   :maxdepth: 3
-   :titlesonly:
-   :caption: Contents:
 
-   core
-   extensions
-   codecs
-   stores
+   Home <https://zarr.dev>
+   specs
+   ZEPs <https://zarr.dev/zeps>
+   Implementations <https://github.com/zarr-developers/zarr_implementations>
 
 
 Indices and tables

docs/requirements.txt

@@ -1,4 +1,5 @@
-sphinx
+sphinx<6.0.0
 pydata-sphinx-theme==0.12.0
 sphinxcontrib-mermaid
 sphinxmark
+sphinx-reredirects

docs/specs.rst

@@ -0,0 +1,25 @@
+==============
+Specifications
+==============
+
+.. toctree::
+   :maxdepth: 1
+   :caption: v3
+
+   Core <v3/core/v3.0>
+   v3/data-types
+   v3/codecs
+   v3/stores
+   v3/array-storage-transformers
+
+.. toctree::
+   :maxdepth: 1
+   :caption: v2
+
+   Zarr spec v2 <https://zarr.readthedocs.io/en/stable/spec/v2.html>
+
+.. toctree::
+   :maxdepth: 1
+   :caption: v1
+
+   Zarr spec v1 <https://zarr.readthedocs.io/en/stable/spec/v1.html>

docs/v3/array-storage-transformers.rst

@@ -0,0 +1,13 @@
+==========================
+Array Storage Transformers
+==========================
+
+Under construction.
+
+.. toctree::
+   :glob:
+   :maxdepth: 1
+   :titlesonly:
+   :caption: Contents:
+
+   array-storage-transformers/*/*

docs/extensions/storage-transformers/sharding/v1.0.rst → docs/v3/array-storage-transformers/sharding/v1.0.rst

@@ -7,7 +7,7 @@ Sharding storage transformer (version 1.0)
   **Editor's draft 18 02 2022**
 
 Specification URI:
-    https://purl.org/zarr/spec/extensions/storage-transformers/sharding/1.0
+    https://zarr-specs.readthedocs.io/en/latest/v3/array-storage-transformers/sharding/v1.0.html
 
 Corresponding ZEP:
     `ZEP 2 — Sharding storage transformer <https://zarr.dev/zeps/draft/ZEP0002.html>`_
@@ -16,7 +16,7 @@ Issue tracking:
     `GitHub issues <https://github.com/zarr-developers/zarr-specs/labels/storage-transformers-sharding-v1.0>`-
 
 Suggest an edit for this spec:
-    `GitHub editor <https://github.com/zarr-developers/zarr-specs/blob/main/docs/extensions/storage-transformers/sharding/v1.0.rst>`_
+    `GitHub editor <https://github.com/zarr-developers/zarr-specs/blob/main/docs/v3/array-storage-transformers/sharding/v1.0.rst>`_
 
 Copyright 2022-Present `Zarr core development team
 <https://github.com/orgs/zarr-developers/teams/core-devs>`_. This work
@@ -94,7 +94,7 @@ Sharding can be configured per array in the :ref:`array-metadata` as follows:
     {
       storage_transformers: [
         {
-          "extension": "https://purl.org/zarr/spec/extensions/storage_transformers/sharding/1.0",
+          "extension": "sharding",
           "type": "indexed",
           "configuration": {
             "chunks_per_shard": [

docs/codecs/blosc/v1.0.rst → docs/v3/codecs/blosc/v1.0.rst

@@ -5,13 +5,13 @@
   **Editor's draft 26 July 2019**
 
 Specification URI:
-    https://purl.org/zarr/spec/codecs/blosc/1.0
+    https://zarr-specs.readthedocs.io/en/latest/v3/codecs/blosc/v1.0.html
 Corresponding ZEP:
     `ZEP 1 — Zarr specification version 3 <https://zarr.dev/zeps/draft/ZEP0001.html>`_
 Issue tracking:
     `GitHub issues <https://github.com/zarr-developers/zarr-specs/labels/codec>`_
 Suggest an edit for this spec:
-    `GitHub editor <https://github.com/zarr-developers/zarr-specs/blob/main/docs/codecs/blosc/v1.0.rst>`_
+    `GitHub editor <https://github.com/zarr-developers/zarr-specs/blob/main/docs/v3/codecs/blosc/v1.0.rst>`_
 
 Copyright 2020 `Zarr core development team
 <https://github.com/orgs/zarr-developers/teams/core-devs>`_. This work
@@ -92,7 +92,7 @@ default block size::
 
     {
         "codecs": [{
-            "type": "https://purl.org/zarr/spec/codecs/blosc/1.0",
+            "type": "blosc",
             "configuration": {
                 "cname": "lz4",
                 "clevel": 1,

docs/codecs/endian/v1.0.rst → docs/v3/codecs/endian/v1.0.rst

@@ -7,13 +7,13 @@
   **Editor's draft 26 July 2019**
 
 Specification URI:
-    https://purl.org/zarr/spec/codecs/endian/1.0
+    https://zarr-specs.readthedocs.io/en/latest/v3/codecs/endian/v1.0.html
 Corresponding ZEP:
     `ZEP 1 — Zarr specification version 3 <https://zarr.dev/zeps/draft/ZEP0001.html>`_
 Issue tracking:
     `GitHub issues <https://github.com/zarr-developers/zarr-specs/labels/codec>`_
 Suggest an edit for this spec:
-    `GitHub editor <https://github.com/zarr-developers/zarr-specs/blob/main/docs/codecs/endian/v1.0.rst>`_
+    `GitHub editor <https://github.com/zarr-developers/zarr-specs/blob/main/docs/v3/codecs/endian/v1.0.rst>`_
 
 Copyright 2020 `Zarr core development team
 <https://github.com/orgs/zarr-developers/teams/core-devs>`_. This work

docs/codecs/gzip/v1.0.rst → docs/v3/codecs/gzip/v1.0.rst

@@ -5,13 +5,13 @@
   **Editor's draft 26 July 2019**
 
 Specification URI:
-    https://purl.org/zarr/spec/codecs/gzip/1.0
+    https://zarr-specs.readthedocs.io/en/latest/v3/codecs/gzip/v1.0.html
 Corresponding ZEP:
     `ZEP 1 — Zarr specification version 3 <https://zarr.dev/zeps/draft/ZEP0001.html>`_
 Issue tracking:
     `GitHub issues <https://github.com/zarr-developers/zarr-specs/labels/codec>`_
 Suggest an edit for this spec:
-    `GitHub editor <https://github.com/zarr-developers/zarr-specs/blob/main/docs/codecs/gzip/v1.0.rst>`_
+    `GitHub editor <https://github.com/zarr-developers/zarr-specs/blob/main/docs/v3/codecs/gzip/v1.0.rst>`_
 
 Copyright 2020 `Zarr core development team
 <https://github.com/orgs/zarr-developers/teams/core-devs>`_. This work
@@ -68,7 +68,7 @@ the Gzip codec configured with a compression level of 1::
 
     {
         "codecs": [{
-            "type": "https://purl.org/zarr/spec/codec/gzip",
+            "type": "gzip",
             "configuration": {                                                                                
                 "level": 1                                                                                    
             }

docs/codecs/transpose/v1.0.rst → docs/v3/codecs/transpose/v1.0.rst

@@ -7,13 +7,13 @@
   **Editor's draft 26 July 2019**
 
 Specification URI:
-    https://purl.org/zarr/spec/codecs/endian/1.0
+    https://zarr-specs.readthedocs.io/en/latest/v3/codecs/transpose/v1.0.html
 Corresponding ZEP:
     `ZEP 1 — Zarr specification version 3 <https://zarr.dev/zeps/draft/ZEP0001.html>`_
 Issue tracking:
     `GitHub issues <https://github.com/zarr-developers/zarr-specs/labels/codec>`_
 Suggest an edit for this spec:
-    `GitHub editor <https://github.com/zarr-developers/zarr-specs/blob/main/docs/codecs/transpose/v1.0.rst>`_
+    `GitHub editor <https://github.com/zarr-developers/zarr-specs/blob/main/docs/v3/codecs/transpose/v1.0.rst>`_
 
 Copyright 2020 `Zarr core development team
 <https://github.com/orgs/zarr-developers/teams/core-devs>`_. This work