Fix Sphinx cross-reference warnings

docs/source/conf.py

@@ -32,12 +32,44 @@
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = [
     "sphinx.ext.autodoc",
+    "sphinx.ext.intersphinx",
     "sphinx.ext.todo",
     "sphinx.ext.coverage",
     "sphinx.ext.ifconfig",
     "sphinx.ext.viewcode",
 ]
 
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+}
+
+# These targets cannot be resolved when building the documentation:
+#
+# * ``Path`` is used unqualified in a few type hints. Because the codebase
+#   uses ``from __future__ import annotations``, annotations are stored as
+#   strings, so intersphinx can only resolve them when they are written with
+#   their fully qualified name (``pathlib.Path``), which isn't the case here.
+# * ``watchdog.utils.bricks.SkipRepeatsQueue`` is shown as a base class of
+#   :class:`watchdog.observers.api.EventQueue` but isn't documented on its
+#   own, since it's considered an implementation detail.
+# * The platform specific observer implementations
+#   (``watchdog.observers.inotify.InotifyObserver``,
+#   ``watchdog.observers.fsevents.FSEventsObserver``,
+#   ``watchdog.observers.kqueue.KqueueObserver`` and
+#   ``watchdog.observers.read_directory_changes.WindowsApiObserver``) can
+#   each only be imported, and therefore documented, on their respective
+#   platform, so at most one of them can ever resolve when building the
+#   documentation on a single machine.
+nitpick_ignore = [
+    ("py:class", "Path"),
+    ("py:class", "watchdog.utils.bricks.SkipRepeatsQueue"),
+    ("py:class", "inotify.InotifyObserver"),
+    ("py:class", "fsevents.FSEventsObserver"),
+    ("py:class", "kqueue.KqueueObserver"),
+    ("py:class", "read_directory_changes.WindowsApiObserver"),
+    ("py:class", "watchdog.observers.fsevents.FSEventsObserver"),
+]
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 

docs/source/quickstart.rst

@@ -20,7 +20,7 @@ to detect changes. Here is what we will do with the API:
 
 By default, an :class:`watchdog.observers.Observer` instance will not monitor
 sub-directories. By passing ``recursive=True`` in the call to
-:meth:`watchdog.observers.Observer.schedule` monitoring
+:meth:`~watchdog.observers.api.BaseObserver.schedule` monitoring
 entire directory trees is ensured.
 
 

src/watchdog/events.py

@@ -211,7 +211,7 @@ def dispatch(self, event: FileSystemEvent) -> None:
         :param event:
             The event object representing the file system event.
         :type event:
-            :class:`FileSystemEvent`
+            :class:`watchdog.events.FileSystemEvent`
         """
         self.on_any_event(event)
         getattr(self, f"on_{event.event_type}")(event)
@@ -222,7 +222,7 @@ def on_any_event(self, event: FileSystemEvent) -> None:
         :param event:
             The event object representing the file system event.
         :type event:
-            :class:`FileSystemEvent`
+            :class:`watchdog.events.FileSystemEvent`
         """
 
     def on_moved(self, event: DirMovedEvent | FileMovedEvent) -> None:
@@ -231,7 +231,7 @@ def on_moved(self, event: DirMovedEvent | FileMovedEvent) -> None:
         :param event:
             Event representing file/directory movement.
         :type event:
-            :class:`DirMovedEvent` or :class:`FileMovedEvent`
+            :class:`watchdog.events.DirMovedEvent` or :class:`watchdog.events.FileMovedEvent`
         """
 
     def on_created(self, event: DirCreatedEvent | FileCreatedEvent) -> None:
@@ -240,7 +240,7 @@ def on_created(self, event: DirCreatedEvent | FileCreatedEvent) -> None:
         :param event:
             Event representing file/directory creation.
         :type event:
-            :class:`DirCreatedEvent` or :class:`FileCreatedEvent`
+            :class:`watchdog.events.DirCreatedEvent` or :class:`watchdog.events.FileCreatedEvent`
         """
 
     def on_deleted(self, event: DirDeletedEvent | FileDeletedEvent) -> None:
@@ -249,7 +249,7 @@ def on_deleted(self, event: DirDeletedEvent | FileDeletedEvent) -> None:
         :param event:
             Event representing file/directory deletion.
         :type event:
-            :class:`DirDeletedEvent` or :class:`FileDeletedEvent`
+            :class:`watchdog.events.DirDeletedEvent` or :class:`watchdog.events.FileDeletedEvent`
         """
 
     def on_modified(self, event: DirModifiedEvent | FileModifiedEvent) -> None:
@@ -258,7 +258,7 @@ def on_modified(self, event: DirModifiedEvent | FileModifiedEvent) -> None:
         :param event:
             Event representing file/directory modification.
         :type event:
-            :class:`DirModifiedEvent` or :class:`FileModifiedEvent`
+            :class:`watchdog.events.DirModifiedEvent` or :class:`watchdog.events.FileModifiedEvent`
         """
 
     def on_closed(self, event: FileClosedEvent) -> None:
@@ -267,7 +267,7 @@ def on_closed(self, event: FileClosedEvent) -> None:
         :param event:
             Event representing file closing.
         :type event:
-            :class:`FileClosedEvent`
+            :class:`watchdog.events.FileClosedEvent`
         """
 
     def on_closed_no_write(self, event: FileClosedNoWriteEvent) -> None:
@@ -276,7 +276,7 @@ def on_closed_no_write(self, event: FileClosedNoWriteEvent) -> None:
         :param event:
             Event representing file closing.
         :type event:
-            :class:`FileClosedNoWriteEvent`
+            :class:`watchdog.events.FileClosedNoWriteEvent`
         """
 
     def on_opened(self, event: FileOpenedEvent) -> None:
@@ -285,7 +285,7 @@ def on_opened(self, event: FileOpenedEvent) -> None:
         :param event:
             Event representing file opening.
         :type event:
-            :class:`FileOpenedEvent`
+            :class:`watchdog.events.FileOpenedEvent`
         """
 
 
@@ -345,7 +345,7 @@ def dispatch(self, event: FileSystemEvent) -> None:
         :param event:
             The event object representing the file system event.
         :type event:
-            :class:`FileSystemEvent`
+            :class:`watchdog.events.FileSystemEvent`
         """
         if self.ignore_directories and event.is_directory:
             return
@@ -430,7 +430,7 @@ def dispatch(self, event: FileSystemEvent) -> None:
         :param event:
             The event object representing the file system event.
         :type event:
-            :class:`FileSystemEvent`
+            :class:`watchdog.events.FileSystemEvent`
         """
         if self.ignore_directories and event.is_directory:
             return

src/watchdog/observers/api.py

@@ -23,8 +23,8 @@
 
 class EventQueue(SkipRepeatsQueue):
     """Thread-safe event queue based on a special queue that skips adding
-    the same event (:class:`FileSystemEvent`) multiple times consecutively.
-    Thus avoiding dispatching multiple event handling
+    the same event (:class:`watchdog.events.FileSystemEvent`) multiple times
+    consecutively. Thus avoiding dispatching multiple event handling
     calls when multiple identical events are produced quicker than an observer
     can consume them.
     """
@@ -108,7 +108,7 @@ class EventEmitter(BaseThread):
     :param event_queue:
         The event queue to populate with generated events.
     :type event_queue:
-        :class:`watchdog.events.EventQueue`
+        :class:`EventQueue`
     :param watch:
         The watch to observe and produce events for.
     :type watch:

src/watchdog/utils/__init__.py

@@ -52,8 +52,8 @@ def should_keep_running(self) -> bool:
         return not self._stopped_event.is_set()
 
     def on_thread_stop(self) -> None:
-        """Override this method instead of :meth:`stop()`.
-        :meth:`stop()` calls this method.
+        """Override this method instead of :meth:`~watchdog.utils.BaseThread.stop`.
+        :meth:`~watchdog.utils.BaseThread.stop` calls this method.
 
         This method is called immediately after the thread is signaled to stop.
         """
@@ -64,8 +64,8 @@ def stop(self) -> None:
         self.on_thread_stop()
 
     def on_thread_start(self) -> None:
-        """Override this method instead of :meth:`start()`. :meth:`start()`
-        calls this method.
+        """Override this method instead of :meth:`~watchdog.utils.BaseThread.start`.
+        :meth:`~watchdog.utils.BaseThread.start` calls this method.
 
         This method is called right before this thread is started and this
         object's run() method is invoked.

src/watchdog/utils/dirsnapshot.py

@@ -359,21 +359,24 @@ def inode(self, path: bytes | str) -> tuple[int, int]:
         return (st.st_ino, st.st_dev)
 
     def isdir(self, path: bytes | str) -> bool:
+        """Returns ``True`` if the path is a directory."""
         return S_ISDIR(self._stat_info[path].st_mode)
 
     def mtime(self, path: bytes | str) -> float:
+        """Returns the last modification time for path."""
         return self._stat_info[path].st_mtime
 
     def size(self, path: bytes | str) -> int:
+        """Returns the size of the file identified by path."""
         return self._stat_info[path].st_size
 
     def stat_info(self, path: bytes | str) -> os.stat_result:
         """Returns a stat information object for the specified path from
         the snapshot.
 
         Attached information is subject to change. Do not use unless
-        you specify `stat` in constructor. Use :func:`inode`, :func:`mtime`,
-        :func:`isdir` instead.
+        you specify `stat` in constructor. Use :meth:`inode`, :meth:`mtime`,
+        :meth:`isdir` instead.
 
         :param path:
             The path for which stat information should be obtained

tox.ini

@@ -23,7 +23,7 @@ deps =
 extras =
     watchmedo
 commands =
-    sphinx-build -aEWb html docs/source docs/build/html
+    sphinx-build -aEWnb html docs/source docs/build/html
 
 [testenv:lint]
 usedevelop = true