Remove specs pages from docs (zarr-developers#2555)

* Remove specs pages from docs

* Add spec doc redirects

* Fix redirects

* Fix index page typo

Co-authored-by: Josh Moore <[email protected]>

---------

Co-authored-by: Josh Moore <[email protected]>

Author: dstansby

docs/conf.py

@@ -47,6 +47,7 @@
     "sphinx_issues",
     "sphinx_copybutton",
     "sphinx_design",
+    'sphinx_reredirects',
 ]
 
 issues_github_path = "zarr-developers/zarr-python"
@@ -81,6 +82,13 @@
 version = get_version("zarr")
 release = get_version("zarr")
 
+redirects = {
+     "spec": "https://zarr-specs.readthedocs.io",
+     "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",
+}
+
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #

docs/contributing.rst

@@ -307,7 +307,8 @@ Data format compatibility
 The data format used by Zarr is defined by a specification document, which should be
 platform-independent and contain sufficient detail to construct an interoperable
 software library to read and/or write Zarr data using any programming language. The
-latest version of the specification document is available from the :ref:`spec` page.
+latest version of the specification document is available on the
+`Zarr specifications website <https://zarr-specs.readthedocs.io>`_.
 
 Here, **data format compatibility** means that all software libraries that implement a
 particular version of the Zarr storage specification are interoperable, in the sense

docs/index.rst

@@ -12,7 +12,6 @@ Zarr-Python
     tutorial
     guide/index
     api/index
-    spec
     release
     license
     contributing
@@ -26,7 +25,8 @@ Zarr-Python
 `Installation <installation.html>`_ |
 `Source Repository <https://github.com/zarr-developers/zarr-python>`_ |
 `Issue Tracker <https://github.com/zarr-developers/zarr-python/issues>`_ |
-`Zulip Chat <https://ossci.zulipchat.com/>`_
+`Zulip Chat <https://ossci.zulipchat.com/>`_ |
+`Zarr specifications <https://zarr-specs.readthedocs.io>`_
 
 Zarr is a file storage format for chunked, compressed, N-dimensional arrays based on an open-source specification.
 

docs/release.rst

@@ -218,17 +218,17 @@ Typing
 Maintenance
 ~~~~~~~~~~~
 
-* Remedy a situation where ``zarr-python`` was importing ``DummyStorageTransformer`` from the test suite. 
+* Remedy a situation where ``zarr-python`` was importing ``DummyStorageTransformer`` from the test suite.
   The dependency relationship is now reversed: the test suite imports this class from ``zarr-python``.
   By :user:`Davis Bennett <d-v-b>` :issue:`1601`.
 
-* [V3] Update minimum supported Python and Numpy versions. 
+* [V3] Update minimum supported Python and Numpy versions.
   By :user:`Joe Hamman <jhamman>` :issue:`1638`
 
 * use src layout and use hatch for packaging.
   By :user:`Davis Bennett <d-v-b>` :issue:`1592`.
 
-* temporarily disable mypy in v3 directory. 
+* temporarily disable mypy in v3 directory.
   By :user:`Joe Hamman <jhamman>` :issue:`1649`.
 
 * create hatch test env.
@@ -315,10 +315,10 @@ Maintenance
 Documentation
 ~~~~~~~~~~~~~
 
-* Specify docs hatch env for v3 branch. 
+* Specify docs hatch env for v3 branch.
   By :user:`Max Jones <maxrjones>` :issue:`1655`.
 
-* Development installation/contributing docs updates. 
+* Development installation/contributing docs updates.
   By :user:`Alden Keefe Sampson <aldenks>` :issue:`1643`.
 
 * chore: update project settings per scientific python repo-review.
@@ -336,7 +336,7 @@ Enhancements
 ~~~~~~~~~~~~
 * Added support for creating a copy of data when converting a `zarr.Array`
   to a numpy array.
-  By :user:`David Stansby <dstansby>` (:issue:`2106`) and 
+  By :user:`David Stansby <dstansby>` (:issue:`2106`) and
   :user:`Joe Hamman <jhamman>` (:issue:`2123`).
 
 Maintenance
@@ -2191,7 +2191,7 @@ Other changes
 ~~~~~~~~~~~~~
 
 To accommodate support for hierarchies and filters, the Zarr metadata format
-has been modified. See the :ref:`spec_v2` for more information. To migrate an
+has been modified. See the ``spec_v2`` for more information. To migrate an
 array stored using Zarr version 1.x, use the :func:`zarr.storage.migrate_1to2`
 function.
 
@@ -2237,14 +2237,14 @@ abstraction layer between the core array logic and data storage (:issue:`21`).
 In this release, any
 object that implements the ``MutableMapping`` interface can be used as
 an array store. See the tutorial sections on :ref:`tutorial_persist`
-and :ref:`tutorial_storage`, the :ref:`spec_v1`, and the
+and :ref:`tutorial_storage`, the ``spec_v1``, and the
 :mod:`zarr.storage` module documentation for more information.
 
 Please note also that the file organization and file name conventions
 used when storing a Zarr array in a directory on the file system have
 changed. Persistent Zarr arrays created using previous versions of the
 software will not be compatible with this version. See the
-:mod:`zarr.storage` API docs and the :ref:`spec_v1` for more
+:mod:`zarr.storage` API docs and the ``spec_v1`` for more
 information.
 
 Compression
@@ -2257,7 +2257,7 @@ as the default compressor, however other compressors including zlib,
 BZ2 and LZMA are also now supported via the Python standard
 library. New compressors can also be dynamically registered for use
 with Zarr. See the tutorial sections on :ref:`tutorial_compress` and
-:ref:`tutorial_tips_blosc`, the :ref:`spec_v1`, and the
+:ref:`tutorial_tips_blosc`, the ``spec_v1``, and the
 :mod:`zarr.compressors` module documentation for more information.
 
 Synchronization

docs/spec.rst

@@ -81,6 +81,7 @@ docs = [
     'sphinx_design',
     'sphinx-issues',
     'sphinx-copybutton',
+    'sphinx-reredirects',
     'pydata-sphinx-theme',
     'numpydoc',
     'numcodecs[msgpack]',

docs/spec/v1.rst

@@ -0,0 +1,7 @@
+import zarr
+
+store = zarr.DirectoryStore("data")
+r = zarr.open_group(store=store)
+z = r.full("myArray", 42, shape=(), dtype="i4", compressor=None)
+
+print(z.oindex[...])