Merge pull request #721 from Fortran-FOSS-Programmers/exclude-dirs-pagetree

Automatically exclude Ford directories from `pages`

Author: ZedThree

ford/__init__.py

@@ -479,6 +479,7 @@ def main(proj_data: ProjectSettings, proj_docs: str):
                 proj_data.copy_subdir,
                 proj_data.output_dir,
                 md,
+                settings=proj_data,
                 encoding=proj_data.encoding,
                 progress=progress,
             )

ford/pagetree.py

@@ -30,7 +30,7 @@
 from textwrap import dedent
 from ford.console import warn
 from ford.utils import meta_preprocessor, ProgressBar
-from ford.settings import EntitySettings
+from ford.settings import EntitySettings, ProjectSettings
 from ford._markdown import MetaMarkdown
 
 
@@ -106,11 +106,25 @@ def __iter__(self):
         return iter(retlist)
 
 
+def is_excluded_dir(path: Path, settings: ProjectSettings) -> bool:
+    """Should `path` be excluded from the pagetree?"""
+    paths_to_exclude: set[Path] = {
+        dir
+        for dir in [settings.graph_dir, settings.media_dir, settings.output_dir]
+        if dir is not None
+    }
+    paths_to_exclude.update(settings.html_template_dir)
+    paths_to_exclude.update(settings.src_dir)
+
+    return path in paths_to_exclude
+
+
 def get_page_tree(
     topdir: Path,
     proj_copy_subdir: Sequence[Path],
     output_dir: Path,
     md: MetaMarkdown,
+    settings: ProjectSettings,
     progress: Optional[ProgressBar] = None,
     parent=None,
     encoding: str = "utf-8",
@@ -124,7 +138,11 @@ def get_page_tree(
     index_file = topdir / "index.md"
 
     if not index_file.exists():
-        warn(f"'{index_file}' does not exist")
+        # Don't warn if this is a Ford input directory (media_dir, graph_dir, etc)
+        if not is_excluded_dir(topdir, settings):
+            warn(
+                f"Skipping creating page for '{topdir}' becase it does not contain 'index.md'"
+            )
         return None
 
     if progress is not None:
@@ -164,7 +182,14 @@ def get_page_tree(
                 continue
 
             if subnode := get_page_tree(
-                filename, proj_copy_subdir, output_dir, md, progress, node, encoding
+                filename,
+                proj_copy_subdir,
+                output_dir,
+                md,
+                settings,
+                progress,
+                node,
+                encoding,
             ):
                 node.subpages.append(subnode)
         elif filename.suffix == ".md":

test/test_pagetree.py

@@ -1,3 +1,5 @@
+from pathlib import Path
+from ford.settings import ProjectSettings
 from ford.pagetree import get_page_tree
 from ford._markdown import MetaMarkdown
 
@@ -29,8 +31,9 @@ def test_footnotes_on_one_page(tmp_path):
             """))
 
     md = MetaMarkdown()
+    settings = ProjectSettings()
     result_dir = tmp_path / "result"
-    nodes = get_page_tree(tmp_path, result_dir, tmp_path / "doc", md)
+    nodes = get_page_tree(tmp_path, result_dir, tmp_path / "doc", md, settings)
 
     assert len(nodes.subpages) == 2
     assert "This is the footnote on page A" in nodes.subpages[0].contents
@@ -61,8 +64,9 @@ def test_footnotes_on_one_page_parse_failure(tmp_path):
             """))
 
     md = MetaMarkdown()
+    settings = ProjectSettings()
     result_dir = tmp_path / "result"
-    nodes = get_page_tree(tmp_path, result_dir, tmp_path / "doc", md)
+    nodes = get_page_tree(tmp_path, result_dir, tmp_path / "doc", md, settings)
 
     assert len(nodes.subpages) == 1
     assert "This is the footnote on page A" not in nodes.subpages[0].contents
@@ -88,7 +92,31 @@ def test_non_utf8_encoding(tmp_path):
         """).encode(encoding))
 
     md = MetaMarkdown()
+    settings = ProjectSettings()
     result_dir = tmp_path / "result"
-    nodes = get_page_tree(tmp_path, result_dir, tmp_path / "doc", md, encoding=encoding)
+    nodes = get_page_tree(
+        tmp_path, result_dir, tmp_path / "doc", md, settings, encoding=encoding
+    )
 
     assert "本文档是" in nodes.contents
+
+
+def test_exclude_ford_dirs(tmp_path, capsys):
+    """Test that we exclude some user-settable directories"""
+
+    (tmp_path / "index.md").write_text("title: Index")
+
+    subdir = tmp_path / "subdir"
+    subdir.mkdir(parents=True)
+
+    media_dir: Path = tmp_path / "media"
+    media_dir.mkdir(parents=True)
+
+    md = MetaMarkdown()
+    settings = ProjectSettings(media_dir=media_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 str(media_dir) not in captured
+    assert str(subdir) in captured