doc: use grid layout for long TOCs

Signed-off-by: Etienne Millon <[email protected]>
ocaml · Mar 22, 2024 · f6bf91d · f6bf91d
1 parent b0666d3
commit f6bf91d
Show file tree

Hide file tree

Showing 6 changed files with 113 additions and 72 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -138,6 +138,7 @@
                   sphinx-autobuild
                   python310Packages.sphinx-copybutton
                   python310Packages.sphinx-rtd-theme
+                  python310Packages.sphinx-design
                 ]
               );
               meta.description = ''