Provide the reason why a document is out of date in all cases (#11572)

Author: larsoner

CHANGES

@@ -37,6 +37,9 @@ Features added
   Patch by Rouslan Korneychuk.
 * #10938: doctest: Add :confval:`doctest_show_successes` option.
   Patch by Trey Hunner.
+* #11572: Improve ``debug`` logging of reasons why files are detected as out of
+  date.
+  Patch by Eric Larson.
 
 Bugs fixed
 ----------

sphinx/environment/__init__.py

@@ -502,10 +502,24 @@ def get_outdated_files(self, config_changed: bool) -> tuple[set[str], set[str],
                         # this will do the right thing when dep is absolute too
                         deppath = path.join(self.srcdir, dep)
                         if not path.isfile(deppath):
+                            logger.debug(
+                                '[build target] changed %r missing dependency %r',
+                                docname, deppath,
+                            )
                             changed.add(docname)
                             break
                         depmtime = _last_modified_time(deppath)
                         if depmtime > mtime:
+                            mtime_dt = datetime.fromtimestamp(
+                                mtime / 1_000_000, tz=timezone.utc,
+                            )
+                            depmtime_dt = datetime.fromtimestamp(
+                                depmtime / 1_000_000, tz=timezone.utc,
+                            )
+                            logger.debug(
+                                '[build target] outdated %r from dependency %r: %s -> %s',
+                                docname, deppath, mtime_dt, depmtime_dt,
+                            )
                             changed.add(docname)
                             break
                     except OSError: