From 5da3e46864253b6f1e45fc35c508def7a1b58208 Mon Sep 17 00:00:00 2001
From: Vaclav Petras <wenzeslaus@gmail.com>
Date: Thu, 6 Mar 2025 13:25:18 -0500
Subject: [PATCH] docs: Use keywords property in MkDocs, not separate tags

Use the keywords front matter property named after keywords of a tool (and used by the custom keywords mechanism), not an additional tags property. This means that keywords property needs to be proper YAML list, not a plain comma-separated list as a string. This is how keywords are now genered. The custom keyword parsing now accepts both version (with and without []).

This does not include any keywords entered manually to Markdown because there are none in this repo, but they are in grass-addons repo which will break the MkDocs reading of the tags from the keywords property (for r.pi, r.green).

This includes cleanup of keywords tool metadata syntax which is supposed to use multiple keyword keys now rather than keywords (for a single keyword).

For the tags page generated by MkDocs, this adds an exclude of keyword 'unit test' which does not need to appear in the documentation.
---
 gui/wxpython/timeline/g.gui.timeline.py | 2 +-
 gui/wxpython/tplot/g.gui.tplot.py       | 8 ++++----
 lib/gis/parser_md.c                     | 5 +----
 man/build_keywords.py                   | 6 +++++-
 man/mkdocs/mkdocs.yml                   | 3 ++-
 man/mkdocs/tags.md                      | 2 +-
 6 files changed, 14 insertions(+), 12 deletions(-)

diff --git a/gui/wxpython/timeline/g.gui.timeline.py b/gui/wxpython/timeline/g.gui.timeline.py
index 3265636a3b0..2b2afc2b01b 100755
--- a/gui/wxpython/timeline/g.gui.timeline.py
+++ b/gui/wxpython/timeline/g.gui.timeline.py
@@ -24,7 +24,7 @@
 # % keyword: general
 # % keyword: GUI
 # % keyword: temporal
-# % keywords: plot
+# % keyword: plot
 # %end
 # %option G_OPT_STDS_INPUTS
 # % required: no
diff --git a/gui/wxpython/tplot/g.gui.tplot.py b/gui/wxpython/tplot/g.gui.tplot.py
index 2cb85a565f8..b95a6be2d02 100755
--- a/gui/wxpython/tplot/g.gui.tplot.py
+++ b/gui/wxpython/tplot/g.gui.tplot.py
@@ -22,10 +22,10 @@
 
 # %module
 # % description: Plots the values of temporal datasets.
-# % keywords: general
-# % keywords: GUI
-# % keywords: temporal
-# % keywords: plot
+# % keyword: general
+# % keyword: GUI
+# % keyword: temporal
+# % keyword: plot
 # %end
 
 # %flag
diff --git a/lib/gis/parser_md.c b/lib/gis/parser_md.c
index d9ae8762726..23b1f2e1a15 100644
--- a/lib/gis/parser_md.c
+++ b/lib/gis/parser_md.c
@@ -49,10 +49,7 @@ void G__usage_markdown(void)
     fprintf(stdout, "---\n");
     fprintf(stdout, "name: %s\n", st->pgm_name);
     fprintf(stdout, "description: %s\n", st->module_info.description);
-    fprintf(stdout, "keywords: ");
-    G__print_keywords(stdout, NULL, FALSE);
-    fprintf(stdout, "\n");
-    fprintf(stdout, "tags: [ ");
+    fprintf(stdout, "keywords: [ ");
     G__print_keywords(stdout, NULL, FALSE);
     fprintf(stdout, " ]");
     fprintf(stdout, "\n---\n\n");
diff --git a/man/build_keywords.py b/man/build_keywords.py
index 0edb0d08fbf..2feffd62e5e 100644
--- a/man/build_keywords.py
+++ b/man/build_keywords.py
@@ -106,7 +106,10 @@ def build_keywords(ext, main_path, addons_path):
         else:
             keys = []
             for line in lines:
-                match = re.match(r"keywords:\s*(.*)", line)
+                # We accept, but don't require, YAML inline list syntax.
+                match = re.match(r"keywords:\s*\[\s*(.*)\s*\]\s*", line)
+                if not match:
+                    match = re.match(r"keywords:\s*(.*)\s*", line)
                 if match:
                     text = match.group(1)
                     if not text:
@@ -114,6 +117,7 @@ def build_keywords(ext, main_path, addons_path):
                             f"Warning: Empty keyword list in {fname}", file=sys.stderr
                         )
                         break
+                    # We accept only non-quoted YAML strings.
                     keys = [item.strip() for item in text.split(",")]
                     break
 
diff --git a/man/mkdocs/mkdocs.yml b/man/mkdocs/mkdocs.yml
index 0ff499dcaf6..29bc6a6afcf 100644
--- a/man/mkdocs/mkdocs.yml
+++ b/man/mkdocs/mkdocs.yml
@@ -75,7 +75,8 @@ extra_css:
 plugins:
   - search
   - glightbox
-  - tags
+  - tags:
+      tags_name_property: keywords
   - social:
       cards_layout_options:
         background_color: rgb(76, 176, 91)
diff --git a/man/mkdocs/tags.md b/man/mkdocs/tags.md
index ab723897e70..020a77cca45 100644
--- a/man/mkdocs/tags.md
+++ b/man/mkdocs/tags.md
@@ -2,4 +2,4 @@
 
 Following is a list of relevant tags:
 
-<!-- material/tags -->
+<!-- material/tags { exclude: [unit test] } -->