From a65314d5da0176224279c11398ff3c76b4cf6878 Mon Sep 17 00:00:00 2001
From: Topi Reinio <topi.reinio@qt.io>
Date: Fri, 26 Apr 2024 13:49:11 +0000
Subject: [PATCH] Doc: Add macros for generating a grid structure of items

These macros generate a a three-column grid of items in online
documentation.

These make for a clutter-free and more visually pleasing result
in many cases, compared to a standard \table layout.

For compatibility reasons, these macros continue to output a table
structure in offline documentation builds.

Task-number: QTWEBSITE-1144
Change-Id: Iab994b383f488dbd225c6a04d64cf41e2dbb20e9
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
---
 doc/global/grid.qdocconf   | 59 ++++++++++++++++++++++++++++++++++++++
 doc/global/macros.qdocconf |  2 ++
 2 files changed, 61 insertions(+)
 create mode 100644 doc/global/grid.qdocconf

diff --git a/doc/global/grid.qdocconf b/doc/global/grid.qdocconf
new file mode 100644
index 00000000000..32b7b2a3cbc
--- /dev/null
+++ b/doc/global/grid.qdocconf
@@ -0,0 +1,59 @@
+# Macros for laying out a three-column grid structure of
+# items in online documentation. Takes three arguments,
+# wrapped in braces:
+#   a link, a title, and a description.
+
+# Usage:
+#   \grid
+#       \griditem {qtqml-index.html} {Qt Qml} {Classes for QML and JavaScript languages.}
+#       \griditem {qtquick-index.html} {Qt Quick} {
+#           Declarative framework for dynamic apps with custom UIs.
+#       }
+#       \griditem {qtquickcontrols-index.html} {Qt Quick Controls} {
+#           Lightweight QML types for creating performant user
+#           interfaces.
+#       }
+#   \endgrid
+
+# Note: For offline documentation, these macros
+# generate a \table structure instead.
+
+
+macro.grid = \
+"\\if defined(onlinedocs)\n" \
+"  \\raw HTML\n" \
+"  <div class=\"grid\">\n" \
+"  <ul class=\"l-tile\" data-column=\"3\">\n" \
+"  \\endraw\n" \
+"\\else\n" \
+"  \\table\n" \
+"\\endif\n"
+
+macro.griditem = \
+"\\detailedgriditem {\1} {\2} {\3} {#} {}"
+
+macro.detailedgriditem = \
+"\\if defined(onlinedocs)\n" \
+"  \\raw HTML\n" \
+"  <li class=\"l-tile__item\">\n" \
+"    <div class=\"c-feature c-feature--external-link\" data-scheme=\"\">\n" \
+"      <h3>\2</h3>\n" \
+"      <p>\3</p>\n" \
+"      <a class=\"c-feature__overlay-link\" href=\"\1\"></a>\n" \
+"      <a data-tag=\"\5\" href=\"\4\"></a>\n" \
+"    </div>\n" \
+"  </li>\n" \
+"  \\endraw\n" \
+"\\else\n" \
+"  \\row \\li \\l {\1}{\2} \\li (\5) \3\n" \
+"\\endif\n"
+
+macro.endgrid = \
+"\\if defined(onlinedocs)\n" \
+"  \\raw HTML\n" \
+"  </ul></div>\n" \
+"  \\endraw\n" \
+"\\else\n" \
+"  \\endtable\n" \
+"\\endif\n"
+
diff --git a/doc/global/macros.qdocconf b/doc/global/macros.qdocconf
index 0bb02323c18..59301ee4488 100644
--- a/doc/global/macros.qdocconf
+++ b/doc/global/macros.qdocconf
@@ -171,3 +171,5 @@ macro.qtpolicydeprecatedbehavior = "\\note The \\c{OLD} behavior of a policy is
 #group.
 #Must be placed directly under a \brief command
 macro.techpreview = "(Technical preview)\n\n\\meta status {Technical preview}\n\\ingroup tech_preview\n"
+
+include(grid.qdocconf)