From f6bf91d6c6deca185a242b56e92d62f77ede9b3d Mon Sep 17 00:00:00 2001
From: Etienne Millon <me@emillon.org>
Date: Tue, 16 Jan 2024 17:40:42 +0100
Subject: [PATCH] doc: use grid layout for long TOCs

Signed-off-by: Etienne Millon <me@emillon.org>
---
 doc/conf.py                        |  1 +
 doc/index.rst                      |  7 ++-
 doc/reference/actions/index.rst    | 84 +++++++++++++++------------
 doc/reference/files/dune/index.rst | 91 +++++++++++++++++++-----------
 doc/requirements.txt               |  1 +
 flake.nix                          |  1 +
 6 files changed, 113 insertions(+), 72 deletions(-)

diff --git a/doc/conf.py b/doc/conf.py
index e7a44dc7d0a..787d0724870 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -41,6 +41,7 @@
 # ones.
 extensions = [
     'sphinx_copybutton',
+    'sphinx_design',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
diff --git a/doc/index.rst b/doc/index.rst
index 4c3f641a320..05b63f9c152 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -1,5 +1,8 @@
-Welcome to Dune's Documentation!
-================================
+Dune Documentation
+==================
+
+Dune is a build system for OCaml projects. Using it, you can build executables,
+libraries, run tests, and much more.
 
 .. toctree::
    :maxdepth: 2
diff --git a/doc/reference/actions/index.rst b/doc/reference/actions/index.rst
index 2f4ef3fadf5..2922aa57f32 100644
--- a/doc/reference/actions/index.rst
+++ b/doc/reference/actions/index.rst
@@ -24,43 +24,53 @@ source code.
 
 The following constructions are available:
 
-.. toctree::
-   :caption: Running commands
-
-   run
-   system
-   bash
-   dynamic-run
-   chdir
-   setenv
-   with-accepted-exit-codes
-
-.. toctree::
-   :caption: Input and output
-
-   echo
-   with-outputs-to
-   with-stdin-from
-   ignore-outputs
-   cat
-   copy
-   copy#
-   write-file
-   pipe-outputs
-
-.. toctree::
-   :caption: Comparing files
-
-   diff
-   diffq
-   cmp
-
-.. toctree::
-   :caption: Control structures
-
-   progn
-   concurrent
-   no-infer
+.. grid:: 1 1 2 2
+
+  .. grid-item::
+  
+    .. toctree::
+       :caption: Running commands
+    
+       run
+       system
+       bash
+       dynamic-run
+       chdir
+       setenv
+       with-accepted-exit-codes
+
+  .. grid-item::
+
+    .. toctree::
+       :caption: Input and output
+    
+       echo
+       with-outputs-to
+       with-stdin-from
+       ignore-outputs
+       cat
+       copy
+       copy#
+       write-file
+       pipe-outputs
+
+  .. grid-item::
+
+    .. toctree::
+       :caption: Comparing files
+    
+       diff
+       diffq
+       cmp
+
+  .. grid-item::
+
+    .. toctree::
+       :caption: Control structures
+    
+       progn
+       concurrent
+       no-infer
 
 Note: expansion of the special ``%{<kind>:...}`` is done relative to the current
 working directory of the DSL being executed. So for instance, if you
diff --git a/doc/reference/files/dune/index.rst b/doc/reference/files/dune/index.rst
index 58a4606dd38..80b42a1f96a 100644
--- a/doc/reference/files/dune/index.rst
+++ b/doc/reference/files/dune/index.rst
@@ -22,36 +22,61 @@ The syntax of ``dune`` files is described in
 
 The following pages describe the available stanzas and their meanings.
 
-.. toctree::
-
-  alias
-  cinaps
-  copy_files
-  coq_theory
-  cram
-  data_only_dirs
-  deprecated_library_name
-  dirs
-  documentation
-  dynamic_include
-  env
-  executable
-  external_variant
-  foreign_library
-  generate_sites_module
-  ignored_subdirs
-  include
-  include_subdirs
-  install
-  jbuild_version
-  library
-  mdx
-  menhir
-  ocamllex
-  ocamlyacc
-  plugin
-  rule
-  subdir
-  test
-  toplevel
-  vendored_dirs
+.. grid:: 1 2 1 3
+
+  .. grid-item::
+
+    .. toctree::
+      :caption: Components
+      :maxdepth: 1
+    
+      executable
+      library
+      foreign_library
+      deprecated_library_name
+      generate_sites_module
+      test
+      cram
+      toplevel
+      documentation
+      install
+      plugin
+
+  .. grid-item::
+    
+    .. toctree::
+      :caption: Project structure
+      :maxdepth: 1
+    
+      rule
+      alias
+      copy_files
+      include
+      dynamic_include
+      env
+      dirs
+      data_only_dirs
+      ignored_subdirs
+      include_subdirs
+      vendored_dirs
+      subdir
+
+  .. grid-item::
+
+    .. toctree::
+      :caption: Integrations
+      :maxdepth: 1
+    
+      cinaps
+      coq_theory
+      mdx
+      menhir
+      ocamllex
+      ocamlyacc
+    
+    .. toctree::
+      :caption: Deprecated
+      :maxdepth: 1
+    
+      external_variant
+      jbuild_version
diff --git a/doc/requirements.txt b/doc/requirements.txt
index 40f63bbf735..d7daba9b3d0 100644
--- a/doc/requirements.txt
+++ b/doc/requirements.txt
@@ -1,3 +1,4 @@
 sphinx >= 4.5.0, < 6
 sphinx_rtd_theme >= 1.0.0
 sphinx-copybutton >= 0.5.0
+sphinx-design
diff --git a/flake.nix b/flake.nix
index 87f6eb6fe25..eab90e148a2 100644
--- a/flake.nix
+++ b/flake.nix
@@ -138,6 +138,7 @@
                   sphinx-autobuild
                   python310Packages.sphinx-copybutton
                   python310Packages.sphinx-rtd-theme
+                  python310Packages.sphinx-design
                 ]
               );
               meta.description = ''