Add support for grid gutters to control spacing between grid items (#693)

This PR closes #596. This was already supported in our sphinx-design
CSS, just that we didn't expose it as a parameter in the `grid`
shortcode, so it was _partially_ implemented (no pun intended :P).

The spacing scale formula is defined here:

https://github.com/scientific-python/scientific-python-hugo-theme/blob/b3056c3a6a9b71813641860e1817aab4086ab55e/assets/theme-css/sphinx-design/_spacing.scss#L1-L9

which generates the responsive `sd-g-*` classes that control the
`--sd-gutter-x` and `--sd-gutter-y` variables.

The gutter parameter can either take one or four integers between 0 to
5. The default is 2 for backwards compatibility. The four integers in
the value, if set, correspond to the `xs`/`sm`/`md`/`lg` breakpoints.
See the Bootstrap docs for more, which is what sphinx-design relies on:
https://getbootstrap.com/docs/5.2/layout/grid/#grid-options

---------

Co-authored-by: Stefan van der Walt <[email protected]>

Author: agriyakhetarpal

layouts/partials/_elements/grid.html

@@ -1,5 +1,6 @@
 {{- $outline := default "false" .outline -}}
 {{- $columns := default "auto" .columns -}}
+{{- $gutter := default "2" .gutter -}}
 {{- $items := .items -}}
 {{- if eq $outline "true" -}}
   {{- $outline = "sd-border-1" -}}
@@ -13,7 +14,19 @@
   {{- $sm := index $columns 1 }}
   {{- $md := index $columns 2 }}
   {{- $lg := index $columns 3 }}
-  <div class="sd-row sd-row-cols-{{ $xs }} sd-row-cols-xs-{{ $xs }} sd-row-cols-sm-{{ $sm }} sd-row-cols-md-{{ $md }} sd-row-cols-lg-{{ $lg }} sd-g-2 sd-g-xs-{{ $xs }} sd-g-sm-{{ $sm }} sd-g-md-{{ $md }} sd-g-lg-{{ $lg }}">
+  {{- $gutterParts := split $gutter " " -}}
+  {{- $gXs := index $gutterParts 0 -}}
+  {{- $gSm := $gXs -}}
+  {{- $gMd := $gXs -}}
+  {{- $gLg := $gXs -}}
+  {{- if and (gt (len $gutterParts) 1) (ne (len $gutterParts) 4) -}}
+    {{- errorf "grid gutter must be either 1 or 4 values (but got %d): %q" (len $gutterParts) $gutter -}}
+  {{- else if eq (len $gutterParts) 4 -}}
+    {{- $gSm = index $gutterParts 1 -}}
+    {{- $gMd = index $gutterParts 2 -}}
+    {{- $gLg = index $gutterParts 3 -}}
+  {{- end -}}
+  <div class="sd-row sd-row-cols-{{ $xs }} sd-row-cols-xs-{{ $xs }} sd-row-cols-sm-{{ $sm }} sd-row-cols-md-{{ $md }} sd-row-cols-lg-{{ $lg }} sd-g-{{ $gXs }} sd-g-xs-{{ $gXs }} sd-g-sm-{{ $gSm }} sd-g-md-{{ $gMd }} sd-g-lg-{{ $gLg }}">
 {{- end }}
 {{- range $key, $item := $items -}}
   {{- if eq $item.type "card" }}

layouts/shortcodes/grid.html

@@ -118,6 +118,83 @@
 
 {{< /grid >}}
 
+Here's a grid with [gutters](https://sphinx-design.readthedocs.io/en/pydata-theme/grids.html#controlling-spacing-between-items).
+A single value applies to all breakpoints.
+
+{{< grid columns="1 2 3 4" gutter="1" >}}
+
+[[item]]
+type = 'card'
+body = 'Tight spacing'
+
+[[item]]
+type = 'card'
+body = 'Tight spacing'
+
+[[item]]
+type = 'card'
+body = 'Tight spacing'
+
+[[item]]
+type = 'card'
+body = 'Tight spacing'
+
+{{< /grid >}}
+
+Here's a grid with no gutters, which means no spacing between items.
+
+{{< grid columns="2 2 2 2" gutter="0" >}}
+
+[[item]]
+type = 'card'
+body = 'No spacing'
+
+[[item]]
+type = 'card'
+body = 'No spacing'
+
+{{< /grid >}}
+
+Here's a grid with responsive gutters (i.e., "xs sm md lg" are set).
+
+{{< grid columns="1 2 2 3" gutter="1 1 3 4" >}}
+
+[[item]]
+type = 'card'
+body = 'Responsive gutter: 0.25rem on mobile, 1rem on tablet, 1.5rem on desktop'
+
+[[item]]
+type = 'card'
+body = 'Responsive gutter: 0.25rem on mobile, 1rem on tablet, 1.5rem on desktop'
+
+[[item]]
+type = 'card'
+body = 'Responsive gutter: 0.25rem on mobile, 1rem on tablet, 1.5rem on desktop'
+
+{{< /grid >}}
+
+And here's a grid with a large gutter, for more spacious layouts.
+
+{{< grid columns="2 2 2 2" gutter="5" >}}
+
+[[item]]
+type = 'card'
+body = 'Large spacing (3rem)'
+
+[[item]]
+type = 'card'
+body = 'Large spacing (3rem)'
+
+{{< /grid >}}
+
+The parameters are based on sphinx-design system grid utilities, which is in-turn based on Bootstrap grid system. They are as follows:
+- 0: 0 (no spacing)
+- 1: 0.25rem
+- 2: 0.5rem (default)
+- 3: 1rem
+- 4: 1.5rem
+- 5: 3rem
+
 */}}
 
 {{- $items := "" -}}