enable excluding files

Author: jalvesz

README.md

@@ -38,6 +38,13 @@ fortran_sources = [
 	"../example/*.f90",  # glob pattern
 ]
 
+# Exclude sources from parsing (directories, files, or glob patterns)
+fortran_sources_exclude = [
+	"../example/legacy",          # directory
+	"../example/skip_this.f90",   # file
+	"../example/**/generated_*.f90",  # glob
+]
+
 # Select a lexer (built-in: "regex")
 fortran_lexer = "regex"
 

src/sphinx_fortran_domain/__init__.py

@@ -158,6 +158,7 @@ def _doc_markers_from_config(app: Sphinx) -> List[str]:
 def _collect_fortran_files(app: Sphinx) -> List[str]:
 	exts = {e.lower() for e in _as_list(getattr(app.config, "fortran_file_extensions", []))}
 	roots = _as_list(getattr(app.config, "fortran_sources", []))
+	excludes = _as_list(getattr(app.config, "fortran_sources_exclude", []))
 	if not roots:
 		return []
 
@@ -183,6 +184,43 @@ def _collect_fortran_files(app: Sphinx) -> List[str]:
 			if not exts or p.suffix.lower() in exts:
 				files.append(str(p))
 
+	if excludes:
+		def _norm(s: str) -> str:
+			try:
+				return os.path.normcase(str(Path(s).resolve()))
+			except Exception:
+				return os.path.normcase(str(Path(s)))
+
+		exclude_files: set[str] = set()
+		confdir = Path(app.confdir)
+		for raw in excludes:
+			pat = str(raw)
+			# Glob patterns
+			if any(ch in pat for ch in "*?["):
+				pattern = str(confdir / pat)
+				for match in glob.glob(pattern, recursive=True):
+					p = Path(match)
+					if p.is_dir():
+						for child in p.rglob("*"):
+							if child.is_file() and (not exts or child.suffix.lower() in exts):
+								exclude_files.add(_norm(str(child)))
+					elif p.is_file() and (not exts or p.suffix.lower() in exts):
+						exclude_files.add(_norm(str(p)))
+				continue
+
+			p = Path(pat)
+			if not p.is_absolute():
+				p = confdir / p
+			if p.is_dir():
+				for child in p.rglob("*"):
+					if child.is_file() and (not exts or child.suffix.lower() in exts):
+						exclude_files.add(_norm(str(child)))
+			elif p.is_file() and (not exts or p.suffix.lower() in exts):
+				exclude_files.add(_norm(str(p)))
+
+		if exclude_files:
+			files = [f for f in files if _norm(f) not in exclude_files]
+
 	# Deterministic order
 	return sorted(set(files))
 
@@ -224,6 +262,7 @@ def setup(app: Sphinx):
 	app.add_domain(FortranDomain)
 
 	app.add_config_value("fortran_sources", default=[], rebuild="env")
+	app.add_config_value("fortran_sources_exclude", default=[], rebuild="env")
 	app.add_config_value("fortran_lexer", default="regex", rebuild="env")
 	app.add_config_value("fortran_doc_chars", default=[">"], rebuild="env")
 	app.add_config_value(

src/sphinx_fortran_domain/directives.py

@@ -65,6 +65,7 @@ def _collect_fortran_files_from_env(env) -> list[str]:
 	confdir = Path(getattr(app, "confdir", os.getcwd()))
 	config = getattr(app, "config", None)
 	roots = _as_list(getattr(config, "fortran_sources", []))
+	excludes = _as_list(getattr(config, "fortran_sources_exclude", []))
 	exts = {e.lower() for e in _as_list(getattr(config, "fortran_file_extensions", []))}
 	if not roots:
 		return []
@@ -91,6 +92,41 @@ def _collect_fortran_files_from_env(env) -> list[str]:
 		if p.is_file() and (not exts or p.suffix.lower() in exts):
 			files.append(str(p))
 
+	if excludes:
+		def _norm(s: str) -> str:
+			try:
+				return os.path.normcase(str(Path(s).resolve()))
+			except Exception:
+				return os.path.normcase(str(Path(s)))
+
+		exclude_files: set[str] = set()
+		for raw in excludes:
+			pat = str(raw)
+			if any(ch in pat for ch in "*?["):
+				pattern = str(confdir / pat)
+				for match in glob.glob(pattern, recursive=True):
+					p = Path(match)
+					if p.is_dir():
+						for child in p.rglob("*"):
+							if child.is_file() and (not exts or child.suffix.lower() in exts):
+								exclude_files.add(_norm(str(child)))
+					elif p.is_file() and (not exts or p.suffix.lower() in exts):
+						exclude_files.add(_norm(str(p)))
+				continue
+
+			p = Path(pat)
+			if not p.is_absolute():
+				p = confdir / p
+			if p.is_dir():
+				for child in p.rglob("*"):
+					if child.is_file() and (not exts or child.suffix.lower() in exts):
+						exclude_files.add(_norm(str(child)))
+			elif p.is_file() and (not exts or p.suffix.lower() in exts):
+				exclude_files.add(_norm(str(p)))
+
+		if exclude_files:
+			files = [f for f in files if _norm(f) not in exclude_files]
+
 	# Deterministic order
 	return sorted(set(files))
 

tests/test_sources_exclude.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from types import SimpleNamespace
+
+
+class _DummyApp:
+    def __init__(self, *, confdir: str, config) -> None:
+        self.confdir = confdir
+        self.config = config
+
+
+def test_fortran_sources_exclude_file_dir_and_glob(tmp_path) -> None:
+    # Layout under the Sphinx confdir
+    src = tmp_path / "src"
+    sub = src / "sub"
+    src.mkdir()
+    sub.mkdir()
+
+    (src / "a.f90").write_text("module a\nend module a\n", encoding="utf-8")
+    (src / "b.f90").write_text("module b\nend module b\n", encoding="utf-8")
+    (src / "skip_me.f90").write_text("module s\nend module s\n", encoding="utf-8")
+    (sub / "c.f90").write_text("module c\nend module c\n", encoding="utf-8")
+
+    config = SimpleNamespace(
+        fortran_sources=["src"],
+        fortran_sources_exclude=[
+            "src/b.f90",      # exclude individual file
+            "src/sub",        # exclude directory
+            "src/*skip*.f90", # exclude via glob
+        ],
+        fortran_file_extensions=[".f90"],
+    )
+    app = _DummyApp(confdir=str(tmp_path), config=config)
+
+    from sphinx_fortran_domain import _collect_fortran_files
+
+    files = _collect_fortran_files(app)
+
+    # Only a.f90 should remain.
+    assert len(files) == 1
+    assert files[0].replace("\\", "/").endswith("/src/a.f90")