Dont try to gen. docs for certain paths

Also, more robust parsing of module to find (or not) docstring

Author: patnr

docs/gen_ref_pages.py

@@ -17,9 +17,27 @@
 src = root
 for path in sorted(src.rglob("*.py")):
 
-    # Skip files that don't have docstrings (avoid build abortion)
+    # Skip "venv" and other similarly named directories
+    if path.name.startswith("venv") or path.name.startswith(".venv") or path.name.startswith(".") or "site-packages" in path.parts:
+        continue
+    # Skip and print "cause"
+    cause = None
+    try:
+        txt = path.read_text()
+    except UnicodeDecodeError:
+        cause = f"Warning: Skipping (due to read error) {path.relative_to(root)}"
+    # Skip files that don't have docstrings (to avoid build abortion)
     # More elaborate solution: https://github.com/mkdocstrings/mkdocstrings/discussions/412
-    if (txt := path.read_text()) and txt.splitlines()[0][0] not in ["'", '"']:
+    if txt and (lines := txt.splitlines()):
+        for line in lines:
+            line = line.strip()
+            if not line or line.startswith("#"):
+                continue
+            if not line.startswith(('"', "'")):
+                print()
+                cause = f"Warning: Skipping (due to missing docstring) {path.relative_to(root)}"
+            break
+    if cause:
         continue
 
     parts = tuple(path.relative_to(src).with_suffix("").parts)