build: Allow separate build of Markdown and HTML keywords

.github/workflows/documentation.yml

@@ -90,7 +90,6 @@ jobs:
           path: grass-addons
 
       - name: Compile addons
-        continue-on-error: true
         run: |
           ./grass-addons/utils/cronjobs_osgeo_lxd/compile_addons_git.sh \
             "$MAJOR" \
@@ -105,19 +104,17 @@ jobs:
           echo MKDOCS_DIR="$(grass --config path)/docs/mkdocs" >> "$GITHUB_ENV"
 
       - name: Move from build to target directory
-        continue-on-error: true
         run: |
-          mkdir -p "$MKDOCS_DIR/source/addons"
-          mv addons-build-dir/docs/md/source/* "$MKDOCS_DIR/source/addons"
+          mkdir "$MKDOCS_DIR/source/addons"
+          mv -v addons-build-dir/docs/md/source/* "$MKDOCS_DIR/source/addons"
 
       - name: Rebuild keywords
-        continue-on-error: true
         run: |
-          export ARCH="linux"
+          export ARCH="$(grass --config arch)"
           export ARCH_DISTDIR="$(grass --config path)"
-          export TOP_DOCS_DIR="${ARCH_DISTDIR}/docs"
           export VERSION_NUMBER="$VERSION"
-          grass --tmp-project XY --exec python grass/man/build_keywords.py "$TOP_DOCS_DIR" "$MKDOCS_DIR/source/addons"
+          grass --tmp-project XY --exec \
+            python grass/man/build_keywords.py md "$MKDOCS_DIR/source" "$MKDOCS_DIR/source/addons"
 
       - name: Get mkdocs
         run: |
@@ -137,8 +134,8 @@ jobs:
         uses: actions/upload-artifact@65c4c4a1ddee5b72f698fdd19549f0f0fb45cf08 # v4.6.0
         with:
           name: grass-addon-build-logs
-          if-no-files-found: warn
-          path: addons-build-dir/docs/logs
+          if-no-files-found: error
+          path: addons-build-dir/logs
           retention-days: 3
 
       - name: Make the result available

man/build_keywords.py

@@ -14,27 +14,37 @@
 python man/build_keywords.py <dir_path_to_core_modules_html_man_files>
     <dir_path_to_addons_modules_html_man_files>
 
+Generate Markdown keywords file:
+
+python man/build_keywords.py md <path_to_core_file> <path_to_addon_files>
+
+If called without parameters, ARCH_DISTDIR environment variable is used
+to determine the path to core documentation. If parameters are provided,
+the variable is ignored, but it must be set regardless.
+
 @author Luca Delucchi
 @author Tomas Zigo <tomas.zigo slovanet.sk> - inject addons modules keywords
+@author Martin Landa - Markdown support
 """
 
 import os
 import sys
 import glob
 
+from build import (
+    grass_version,
+    write_footer,
+)
+
 keywords_to_hide_in_overview = [
     "General",
     "Misc",
 ]
 
-addons_path = None
-if len(sys.argv) >= 2:
-    addons_path = sys.argv[1]
-
 year = os.getenv("VERSION_DATE")
 
 
-def get_module_man_file_path(man_dir, module, addons_man_files):
+def get_module_man_file_path(man_dir, addons_path, module, addons_man_files):
     """Get module manual HTML file path
 
     :param str module: module manual HTML file name e.g. v.surf.rst.html
@@ -53,7 +63,7 @@ def get_module_man_file_path(man_dir, module, addons_man_files):
     return module_path
 
 
-def build_keywords(ext):
+def build_keywords(ext, main_path, addons_path):
     if ext == "html":
         from build_html import header1_tmpl, headerkeywords_tmpl, man_dir
     else:
@@ -65,16 +75,16 @@ def build_keywords(ext):
 
     keywords = {}
 
-    files = glob.glob(os.path.join(man_dir, f"*.{ext}"))
+    main_doc_dir = main_path or man_dir
+
+    files = glob.glob(os.path.join(main_doc_dir, f"*.{ext}"))
     # TODO: add markdown support
     if addons_path:
         addons_man_files = glob.glob(os.path.join(addons_path, f"*.{ext}"))
         files.extend(addons_man_files)
     else:
         addons_man_files = []
 
-    char_list = {}
-
     for in_file in files:
         fname = os.path.basename(in_file)
         with open(in_file) as f:
@@ -115,17 +125,23 @@ def build_keywords(ext):
             except Exception:
                 continue
 
-    for key in sorted(keywords.keys()):
-        # this list it is useful to create the TOC using only the first
-        # character for keyword
-        firstchar = key[0].lower()
-        if firstchar not in char_list.keys():
-            char_list[str(firstchar)] = key
-        elif firstchar in char_list.keys():
-            if key.lower() < char_list[str(firstchar)].lower():
-                char_list[str(firstchar.lower())] = key
-
-    with open(os.path.join(man_dir, f"keywords.{ext}"), "w") as keywordsfile:
+    def create_char_list(keywords):
+        """Create a dict with the first letters and corresponding first keywords.
+
+        This list it is useful to create the TOC using only the first character
+        for keyword.
+        """
+        char_list = {}
+        for key in sorted(keywords.keys()):
+            firstchar = key[0].lower()
+            if firstchar not in char_list.keys():
+                char_list[str(firstchar)] = key
+            elif firstchar in char_list.keys():
+                if key.lower() < char_list[str(firstchar)].lower():
+                    char_list[str(firstchar.lower())] = key
+        return char_list
+
+    with open(os.path.join(main_doc_dir, f"keywords.{ext}"), "w") as keywordsfile:
         keywordsfile.write(
             header1_tmpl.substitute(
                 title=f"GRASS GIS {grass_version} Reference Manual - Keywords index"
@@ -145,7 +161,10 @@ def build_keywords(ext):
                 keyword_line = f"### **{key}**\n"
             for value in sorted(keywords[key]):
                 man_file_path = get_module_man_file_path(
-                    man_dir, value, addons_man_files
+                    man_dir=main_doc_dir,
+                    addons_path=addons_path,
+                    module=value,
+                    addons_man_files=addons_man_files,
                 )
                 if ext == "html":
                     keyword_line += f' <a href="{man_file_path}">{value.replace(f".{ext}", "")}</a>,'  # noqa: E501
@@ -162,6 +181,7 @@ def build_keywords(ext):
             # create toc
             toc = '<div class="toc">\n<h4 class="toc">Table of contents</h4><p class="toc">'  # noqa: E501
             test_length = 0
+            char_list = create_char_list(keywords)
             all_keys = len(char_list.keys())
             for k in sorted(char_list.keys()):
                 test_length += 1
@@ -180,12 +200,33 @@ def build_keywords(ext):
         write_footer(keywordsfile, f"index.{ext}", year, template=ext)
 
 
-if __name__ == "__main__":
-    from build import (
-        grass_version,
-        write_footer,
-    )
+def main():
+    if len(sys.argv) == 1:
+        # Usage according to a Makefile in core after the initial Markdown doc
+        # implementation.
+        build_keywords("html", main_path=None, addons_path=None)
+        build_keywords("md", main_path=None, addons_path=None)
+        return
+
+    if len(sys.argv) >= 2:
+        doc_type = sys.argv[1]
+    if doc_type in ["html", "md"]:
+        offset = 1
+    else:
+        # The original usage according to the build sever scripts.
+        offset = 0
+        doc_type = "html"
 
-    build_keywords("html")
+    # Usage allowing to pick Markdown-only build.
+    main_path = None
+    if len(sys.argv) >= 2 + offset:
+        main_path = sys.argv[1 + offset]
+    addons_path = None
+    if len(sys.argv) >= 3 + offset:
+        addons_path = sys.argv[2 + offset]
 
-    build_keywords("md")
+    build_keywords(doc_type, main_path=main_path, addons_path=addons_path)
+
+
+if __name__ == "__main__":
+    main()