Give reason when ignoring directories under page_dir

Author: ZedThree

ford/pagetree.py

@@ -106,17 +106,25 @@ def __iter__(self):
         return iter(retlist)
 
 
-def is_excluded_dir(path: Path, settings: ProjectSettings) -> bool:
+def is_excluded_dir(path: Path, settings: ProjectSettings) -> Optional[str]:
     """Should `path` be excluded from the pagetree?"""
-    paths_to_exclude: set[Path] = {
-        path
-        for path in [settings.graph_dir, settings.media_dir, settings.output_dir]
-        if path is not None
-    }
-    paths_to_exclude.update(settings.html_template_dir)
-    paths_to_exclude.update(settings.src_dir)
 
-    return path in paths_to_exclude
+    if path == settings.graph_dir:
+        return "it is set as 'graph_dir'"
+
+    if path == settings.media_dir:
+        return "it is set as 'media_dir'"
+
+    if path == settings.output_dir:
+        return "it is set as 'output_dir'"
+
+    if path in settings.html_template_dir:
+        return "it is set as 'html_template_dir'"
+
+    if path in settings.src_dir:
+        return "it is set as 'src_dir'"
+
+    return None
 
 
 def get_page_tree(
@@ -134,13 +142,19 @@ def get_page_tree(
     # I will use this later to remove duplicates from a list in a short way.
     from collections import OrderedDict
 
-    if is_excluded_dir(topdir, settings):
-        # Would be nice to be able to report if directory was excluded and why
-        return None
-
     # look for files within topdir
     index_file = topdir / "index.md"
 
+    # Ignore Ford directories if they're under `page_dir`, giving a warning if
+    # there's an `index.md` under them
+    if (reason := is_excluded_dir(topdir, settings)) is not None:
+        if index_file.exists():
+            warn(
+                f"Ignoring '{topdir}' from pages, because {reason}.\n"
+                f"    Either remove '{index_file}' or move it to another directory\n"
+            )
+        return None
+
     if not index_file.exists():
         warn(f"'{index_file}' does not exist")
         return None

test/test_pagetree.py

@@ -104,16 +104,20 @@ def test_non_utf8_encoding(tmp_path):
 def test_exclude_ford_dirs(tmp_path, capsys):
     """Test that we exclude some user-settable directories"""
 
-    with open(tmp_path / "index.md", "w") as f:
-        f.write("title: Index")
+    (tmp_path / "index.md").write_text("title: Index")
 
     media_dir: Path = tmp_path / "media"
     media_dir.mkdir(parents=True)
 
+    graph_dir: Path = tmp_path / "graph"
+    graph_dir.mkdir(parents=True)
+    (graph_dir / "index.md").write_text("title: Graphs")
+
     md = MetaMarkdown()
-    settings = ProjectSettings(media_dir=media_dir)
+    settings = ProjectSettings(media_dir=media_dir, graph_dir=graph_dir)
     result_dir = tmp_path / "result"
     get_page_tree(tmp_path, result_dir, tmp_path / "doc", md, settings)
 
     captured = capsys.readouterr().out.replace("\n", " ").replace("  ", " ")
     assert f"'{media_dir / 'index.md'}' does not exist" not in captured
+    assert f"Ignoring '{graph_dir}'" in captured