docs: Use YAML list for keywords in front matter (#5320)

To use the keywords directly in MkDocs, keywords property needs to be proper YAML list, not a plain comma-separated list as a string. The keywords are now generated like that, and 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). Addons are addressed in OSGeo/grass-addons#1357.

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.

This covers only the YAML changes for keywords. The MkDocs change for tags to keywords is in #5318.

Author: wenzeslaus

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

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

lib/gis/parser_md.c

@@ -49,9 +49,9 @@ 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: ");
+    fprintf(stdout, "keywords: [ ");
     G__print_keywords(stdout, NULL, FALSE);
-    fprintf(stdout, "\n");
+    fprintf(stdout, " ]");
     fprintf(stdout, "tags: [ ");
     G__print_keywords(stdout, NULL, FALSE);
     fprintf(stdout, " ]");

man/build_keywords.py

@@ -106,14 +106,18 @@ 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:
                         print(
                             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
 

man/mkdocs/tags.md

@@ -2,4 +2,4 @@
 
 Following is a list of relevant tags:
 
-<!-- material/tags -->
+<!-- material/tags { exclude: [unit test] } -->