Merge pull request #204 from scalableminds/restructure-and-shord-ids

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

Author: jstriebel

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/core.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/extensions.rst

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

docs/extensions/array-extensions.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>