doc: genrest: Use , instead of : as the separator in --modules

Using ':' as the separator in --modules breaks module specifications
like

    nrfxlib:nrfxlib:C:/Users/Carles/src/ncs/nrfxlib

The ':' in 'C:' gets seen as a separator.

Use ',' instead, which is unlikely to appear in paths (at least in
--modules). Treat a doubled ',,' as a literal ','.

Another option would be ';', but it clashes with how CMake represents
lists, which is awkward.

Also make quoting of arguments with spaces more robust by passing
VERBATIM to add_custom_target().

Signed-off-by: Ulf Magnusson <[email protected]>

Author: ulfalizer

doc/CMakeLists.txt

@@ -194,7 +194,7 @@ add_custom_target(
   kconfig
   COMMAND ${CMAKE_COMMAND} -E make_directory ${RST_OUT}/doc/reference/kconfig
   COMMAND ${CMAKE_COMMAND} -E env
-  PYTHONPATH="${ZEPHYR_BASE}/scripts/kconfig${SEP}$ENV{PYTHONPATH}"
+  PYTHONPATH=${ZEPHYR_BASE}/scripts/kconfig${SEP}$ENV{PYTHONPATH}
   ZEPHYR_BASE=${ZEPHYR_BASE}
   srctree=${ZEPHYR_BASE}
   BOARD_DIR=boards/*/*
@@ -207,13 +207,14 @@ add_custom_target(
   KCONFIG_DOC_MODE=1
     ${PYTHON_EXECUTABLE} scripts/genrest.py ${RST_OUT}/doc/reference/kconfig/
       --keep-module-paths
-      --modules Architecture:arch:${ZEPHYR_BASE}/arch
-                Driver:drivers:${ZEPHYR_BASE}/drivers
-                Kernel:kernel:${ZEPHYR_BASE}/kernel
-                Library:lib:${ZEPHYR_BASE}/lib
-                Subsystem:subsys:${ZEPHYR_BASE}/subsys
-                'External Module':modules:${ZEPHYR_BASE}/modules
-
+      --modules Architecture,arch,${ZEPHYR_BASE}/arch
+                Driver,drivers,${ZEPHYR_BASE}/drivers
+                Kernel,kernel,${ZEPHYR_BASE}/kernel
+                Library,lib,${ZEPHYR_BASE}/lib
+                Subsystem,subsys,${ZEPHYR_BASE}/subsys
+                "External Module,modules,${ZEPHYR_BASE}/modules"
+
+  VERBATIM
   WORKING_DIRECTORY ${CMAKE_CURRENT_LIST_DIR}
   COMMENT "Running genrest.py Kconfig ${RST_OUT}/doc/reference/kconfig/"
 )

doc/scripts/genrest.py

@@ -106,15 +106,21 @@ def init():
 
     modules = []
     for module_spec in args.modules:
-        if module_spec.count(":") == 2:
-            title, suffix, path_s = module_spec.split(":")
+        # Split on ',', but keep any ',,' as a literal ','. Temporarily
+        # represent a literal comma with null.
+        spec_parts = [part.replace("\0", ",")
+                      for part in module_spec.replace(",,", "\0").split(",")]
+
+        if len(spec_parts) == 3:
+            title, suffix, path_s = spec_parts
             desc_path = None
-        elif module_spec.count(":") == 3:
-            title, suffix, path_s, desc_path = module_spec.split(":")
+        elif len(spec_parts) == 4:
+            title, suffix, path_s, desc_path = spec_parts
         else:
             sys.exit("error: --modules argument '{}' should have the format "
-                     "<title>:<suffix>:<path> or the format "
-                     "<title>:<suffix>:<path>:<index description filename>"
+                     "<title>,<suffix>,<path> or the format "
+                     "<title>,<suffix>,<path>,<index description filename>. "
+                     "A doubled ',,' in any part is treated as a literal comma."
                      .format(module_spec))
 
         abspath = pathlib.Path(path_s).resolve()
@@ -160,10 +166,13 @@ def parse_args():
 
 Each MODULE_SPECIFICATION has the form
 
-    <title>:<suffix>:<path>[:<index description path>]
+    <title>,<suffix>,<path>[,<index description path>]
 
 , where <index description path> is optional.
 
+To insert a literal comma into any of the parts, double it,
+e.g. 'My title,, with a comma'.
+
 A separate index-<suffix>.rst symbol index page is generated
 for each MODULE_SPECIFICATION, with links to all symbols
 that are defined inside <path> (possibly more than one level