diff --git a/docs/source/conf.py b/docs/source/conf.py
index 11a7029717..f1d7007707 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -63,13 +63,21 @@ def _build_api_tree() -> Path:
     with open(dest_dir / "__init__.py", "w", encoding="utf-8") as f:
         f.write("")
 
+    # Subpackages excluded from the generated API tree. ``nat.plugin_api`` is the public
+    # plugin-author facade that re-exports symbols from their canonical modules; including it
+    # here would register duplicate cross-reference targets (e.g. ``InvocationContext`` in both
+    # ``nat.plugin_api`` and ``nat.middleware.middleware``) and trip the docs build's ``-W``.
+    # TODO: once the docs are restructured to make ``nat.plugin_api`` the canonical reference
+    # for plugin authors, remove this exclusion and invert the resolution direction.
+    skip_from_api_docs = {"plugin_api"}
+
     plugin_dirs = [Path(p) for p in glob.glob(f'{plugins_dir}/nvidia_nat_*')]
     for plugin_dir in plugin_dirs:
         src_dir = plugin_dir / 'src/nat'
         print(f"Copying {src_dir} to {dest_dir}")
         if src_dir.exists():
             for plugin_subdir in src_dir.iterdir():
-                if plugin_subdir.is_dir():
+                if plugin_subdir.is_dir() and plugin_subdir.name not in skip_from_api_docs:
                     dest_subdir = dest_dir / plugin_subdir.name
                     shutil.copytree(plugin_subdir, dest_subdir, dirs_exist_ok=True)
                     package_file = dest_subdir / "__init__.py"
diff --git a/packages/nvidia_nat_core/src/nat/plugin_api.py b/packages/nvidia_nat_core/src/nat/plugin_api/__init__.py
similarity index 100%
rename from packages/nvidia_nat_core/src/nat/plugin_api.py
rename to packages/nvidia_nat_core/src/nat/plugin_api/__init__.py