ci(check_toc_txt): add warning for files not in toc

Add a new warning for RST files in the source directory that are
unreachable, as they are not listed in any device table of contents.

Signed-off-by: Randolph Sapp <[email protected]>

Author: StaticRocket

bin/check_toc_txt.py

@@ -18,34 +18,57 @@
 logger = logging.getLogger(__name__)
 
 
-def is_slug(slug):
-    """Check to see if the given slug is valid. Assumes extension will be rst.
+def get_slug_path(slug):
+    """Convert the given slug to a pathlib path. Assumes extension will be rst.
 
     :param slug: String path slug
     """
     path = SOURCE_PATH.joinpath(slug + ".rst")
     logging.debug("Expanded slug: %s", path)
-    return path.is_file()
+    return path
 
 
 def process_toc_txt(path):
     """Process a single toc.txt file
 
     :param path: Pathlib path to toc.txt
+    :return: Set of valid paths
     """
+    valid_paths = set()
     with path.open("r", encoding="utf-8") as file:
         logging.debug("Processing %s", path)
         for line_number, line in enumerate(file):
             clean_line = COMMENT_REGEX.sub("", line).strip()
-            if clean_line and not is_slug(clean_line):
-                logging.warning("Invalid slug: %s:%i %s", path, line_number + 1, clean_line)
+            if clean_line:
+                slug_path = get_slug_path(clean_line)
+                if slug_path.is_file():
+                    valid_paths.add(slug_path)
+                else:
+                    logging.warning(
+                        "Invalid slug: %s:%i %s", path, line_number + 1, clean_line
+                    )
+    return valid_paths
+
+
+def process_src_tree(toc_paths):
+    """Ensure all RST files in the src tree are listed in the given set"""
+    src_paths = set()
+    for path in SOURCE_PATH.glob("**/*.rst"):
+        # files that begin with an underscore are included by other rst files
+        # they should not be listed in the toc
+        if path.stem[0] != "_":
+            src_paths.add(path)
+    for path in src_paths - toc_paths:
+        logging.warning("File not in any toc: %s", path)
 
 
 def process_all():
     """Process all toc.txt files in the config directory"""
+    toc_paths = set()
     for path in CONFIG_PATH.glob("**/*toc.txt"):
         if path.is_file():
-            process_toc_txt(path)
+            toc_paths |= process_toc_txt(path)
+    process_src_tree(toc_paths)
 
 
 def main():