add verbose parameter to script to improve logging

Author: Blargian

plugins/checkFloatingPages.js

@@ -0,0 +1,85 @@
+const fs = require('fs');
+const path = require('path');
+const { promisify } = require('util');
+const glob = promisify(require('glob'));
+const matter = require('gray-matter');
+
+async function checkFloatingPages(context, options) {
+    return {
+        name: 'check-floating-pages',
+
+        async postBuild({ siteConfig, routesPaths, outDir, head }) {
+            const { baseUrl } = siteConfig;
+            const docsDir = path.resolve(context.siteDir, 'docs');
+
+            let sidebarItems = [];
+            const sidebarsPath = path.join(context.siteDir, 'sidebars.js');
+            if (fs.existsSync(sidebarsPath)) {
+                try {
+                    const sidebars = require(sidebarsPath);
+                    sidebarItems = getSidebarItems(sidebars);
+                } catch (err) {
+                    console.error("Error loading sidebars.js", err);
+                    throw err; // Stop the build
+                }
+            }
+
+            const markdownFiles = await glob(path.join(docsDir, '**/*.md'));
+            const floatingPages = [];
+
+            for (const filePath of markdownFiles) {
+                const fileContent = fs.readFileSync(filePath, 'utf-8');
+                const { data } = matter(fileContent);
+
+                const relativePath = path.relative(docsDir, filePath).replace(/\\/g, '/').replace(/\.md$/, '');
+
+                // Check 1: Explicit sidebar_position or id in frontmatter
+                if (data.sidebar_position || data.id) {
+                    const idToCheck = data.id || relativePath;
+                    if (!sidebarItems.includes(idToCheck)) {
+                        floatingPages.push(filePath);
+                    }
+                } else {
+                    //Check 2: Implicit.
+                    if (!sidebarItems.includes(relativePath)) {
+                        floatingPages.push(filePath);
+                    }
+                }
+            }
+
+            if (floatingPages.length > 0) {
+                console.error('\x1b[31m%s\x1b[0m', 'Floating pages found:');
+                floatingPages.forEach(page => console.error(`  - ${page}`));
+                if (options && options.failBuild) {
+                    throw new Error('Floating pages found. See above for details.');
+                }
+            } else {
+                console.log('\x1b[32m%s\x1b[0m', 'No floating pages found.');
+            }
+        }
+    }
+}
+
+function getSidebarItems(sidebarConfig) {
+    let items = []
+    function traverse(item) {
+        if (item.type === 'doc') {
+            items.push(item.id);
+        } else if (item.type === 'category' || item.type === 'autogenerated') {
+            (item.items || []).forEach(traverse);
+        } else if (item.type === 'link') {
+            // no need to worry about links
+        }
+    }
+    // sidebarConfig can be an array or an object
+    if (Array.isArray(sidebarConfig)) {
+        sidebarConfig.forEach(traverse);
+    } else {
+        Object.values(sidebarConfig).forEach(sidebar => {
+            sidebar.forEach(traverse)
+        })
+    }
+    return items;
+}
+
+module.exports = checkFloatingPages;

scripts/table-of-contents-generator/toc_gen.py

@@ -39,9 +39,19 @@ def parse_args() -> argparse.Namespace:
     )
     parser.add_argument('--ignore', metavar='S', type=str, nargs='+',
                         help='Directory names to ignore. E.g --ignore _snippets images')
+    parser.add_argument(
+        "--verbose",
+        action="store_true",
+        help="Enable verbose logging"
+    )
     return parser.parse_args()
 
-def extract_title_description_slug(filename):
+def log(message, verbose=False):
+    """Print message only if verbose mode is enabled"""
+    if verbose:
+        print(message)
+
+def extract_title_description_slug(filename, verbose=False):
     data = defaultdict(str)
     missing_fields = []
     frontmatter_data = {}
@@ -63,29 +73,30 @@ def extract_title_description_slug(filename):
 
         data.update(frontmatter_data)
 
-        if missing_fields:
-            print(f"Warning: {filename} is missing some fields:")
+        if missing_fields and verbose:
+            log(f"Warning: {filename} is missing some fields:", verbose)
             for field in missing_fields:
-                print(f"- {field}")
+                log(f"- {field}", verbose)
 
         return frontmatter_data
     except OSError as e:
-        print(f"Ran into a problem reading frontmatter: {e}")
+        log(f"Ran into a problem reading frontmatter: {e}", verbose)
         sys.exit(1)
-def walk_dirs(root_dir, ignore_dirs=[]):
+
+def walk_dirs(root_dir, ignore_dirs=[], verbose=False):
     for root, dirs, files in os.walk(root_dir):
         # Modify the 'dirs' list in-place to remove ignored directories
         if (ignore_dirs is not None):
             dirs[:] = [d for d in dirs if d not in ignore_dirs
-                    and not any(d.startswith(ig) for ig in ignore_dirs)]
+                       and not any(d.startswith(ig) for ig in ignore_dirs)]
         yield root
 
-def write_md_to_file(json_items, path_to_md_file):
+def write_md_to_file(json_items, path_to_md_file, verbose=False):
     try:
         with open(path_to_md_file, encoding='utf-8') as pre_check:
             existing_content = pre_check.read()
             if "| Page | Description |" in existing_content:
-                print(f"Markdown table already exists in {path_to_md_file}. Skipping.")
+                log(f"Markdown table already exists in {path_to_md_file}. Skipping.", verbose)
                 return
 
         with open(path_to_md_file, 'a', encoding='utf-8') as f:
@@ -100,12 +111,12 @@ def write_md_to_file(json_items, path_to_md_file):
                 link = f"[{title}]({slug})" if slug else title
                 f.write(f"| {link} | {description} |\n")
 
-        print(f"Markdown table appended to {path_to_md_file}")
+        log(f"Markdown table appended to {path_to_md_file}", verbose)
 
     except Exception as e:
-        print(f"An error occurred: {e}")
-def write_to_file(json_items, directory, output=None):
+        log(f"An error occurred: {e}", verbose)
 
+def write_to_file(json_items, directory, output=None, verbose=False):
     if output is not None:
         # output to the given path the toc.json file
         # If dir='docs/en/interfaces/formats' the file is called docs_en_interfaces_formats_toc.json
@@ -117,20 +128,21 @@ def write_to_file(json_items, directory, output=None):
         with open(output_path, "w") as f:
             json.dump(json_items, f, indent=4, default=str)
             f.write('\n')
-            print(f"Wrote {output_path}")
+            log(f"Wrote {output_path}", verbose)
     except OSError as e:
         if e.errno == 21:
-            print(f"Directory already exists: {e}")
+            log(f"Directory already exists: {e}", verbose)
         elif e.errno != 17:
-            print(f"An error occurred creating directory: {e}")
+            log(f"An error occurred creating directory: {e}", verbose)
+
 def write_file(json_items, args, directory):
-    print(args)
     if (args.out is not None) and (args.md is None):
-        write_to_file(json_items, directory+"/toc.json", args.out)
+        write_to_file(json_items, directory+"/toc.json", args.out, args.verbose)
     elif (args.out is None) and (args.md is None):
-        write_to_file(json_items, directory+"/toc.json")
+        write_to_file(json_items, directory+"/toc.json", verbose=args.verbose)
     elif (args.out is None) and (args.md is not None):
-        write_md_to_file(json_items, args.md)
+        write_md_to_file(json_items, args.md, args.verbose)
+
 def sort_by_title_before_underscore(json_items):
     def sort_key(item):
         title = item.get("title", "")
@@ -142,21 +154,19 @@ def sort_key(item):
     return sorted(json_items, key=sort_key)
 
 def main():
-
     # Extract script arguments
     args = parse_args()
     root_dir = args.dir
     if root_dir is None:
-        print("Please provide a directory with argument --dir")
+        log("Please provide a directory with argument --dir", True)  # Always show critical errors
         sys.exit(1)
     if os.path.lexists(root_dir) is False:
-        print("Path provided does not exist")
+        log("Path provided does not exist", True)  # Always show critical errors
         sys.exit(1)
     if args.single_toc is True:
         json_items = [] # single list for all directories
 
-    for directory in walk_dirs(root_dir, args.ignore): # Walk directories
-
+    for directory in walk_dirs(root_dir, args.ignore, args.verbose): # Walk directories
         if args.single_toc is False:
             json_items = [] # new list for each directory
 
@@ -167,7 +177,7 @@ def main():
             else:
                 # index.md is ignored as we expect this to be the page for the table of contents
                 if (filename.endswith(".md") or filename.endswith(".mdx")) and filename != "index.md":
-                    result = extract_title_description_slug(full_path)
+                    result = extract_title_description_slug(full_path, args.verbose)
                     if result is not None:
                         json_items.append(result)
                         if args.single_toc is False:
@@ -177,7 +187,7 @@ def main():
                                 # output to the specified directory if arg --out is provided
                                 write_file(json_items, args, directory)
                             else:
-                                print("Ran into an issue trying to extract YAML: empty result")
+                                log("Ran into an issue trying to extract YAML: empty result", args.verbose)
 
         if args.single_toc is True:
             # don't write toc.json for empty folders
@@ -190,5 +200,4 @@ def main():
                 sys.exit(1)
 
 if __name__ == "__main__":
-    main()
-
+    main()