From 6dc4e3fad05b8997e94bd9b61f7b0426c9b13624 Mon Sep 17 00:00:00 2001
From: Casey Brooks <casey.brooks@agyn.io>
Date: Fri, 26 Dec 2025 18:06:02 +0000
Subject: [PATCH] fix(autodoc): honor attr metadata privacy

---
 sphinx/ext/autodoc/__init__.py                  |  8 ++++++++
 .../target/meta_doc_comments.py                 |  2 ++
 tests/test_ext_autodoc_attr_metadata.py         | 17 +++++++++++++++++
 3 files changed, 27 insertions(+)
 create mode 100644 tests/roots/test-ext-autodoc/target/meta_doc_comments.py
 create mode 100644 tests/test_ext_autodoc_attr_metadata.py

diff --git a/sphinx/ext/autodoc/__init__.py b/sphinx/ext/autodoc/__init__.py
index 76265f5bea1..a6854eaf169 100644
--- a/sphinx/ext/autodoc/__init__.py
+++ b/sphinx/ext/autodoc/__init__.py
@@ -729,6 +729,14 @@ def is_filtered_inherited_member(name: str, obj: Any) -> bool:
             has_doc = bool(doc)
 
             metadata = extract_metadata(doc)
+            attr_doc = attr_docs.get((namespace, membername))
+            if attr_doc:
+                if isinstance(attr_doc, (list, tuple)):
+                    attr_doc = '\n'.join(attr_doc)
+                attr_metadata = extract_metadata(attr_doc)
+                if attr_metadata:
+                    metadata = {**attr_metadata, **metadata}
+
             if 'private' in metadata:
                 # consider a member private if docstring has "private" metadata
                 isprivate = True
diff --git a/tests/roots/test-ext-autodoc/target/meta_doc_comments.py b/tests/roots/test-ext-autodoc/target/meta_doc_comments.py
new file mode 100644
index 00000000000..b662976f2e6
--- /dev/null
+++ b/tests/roots/test-ext-autodoc/target/meta_doc_comments.py
@@ -0,0 +1,2 @@
+#: :meta public:
+_foo = None
diff --git a/tests/test_ext_autodoc_attr_metadata.py b/tests/test_ext_autodoc_attr_metadata.py
new file mode 100644
index 00000000000..a82ca3bf233
--- /dev/null
+++ b/tests/test_ext_autodoc_attr_metadata.py
@@ -0,0 +1,17 @@
+"""
+    test_ext_autodoc_attr_metadata
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+    Tests for autodoc behavior around metadata in attribute doc comments.
+"""
+
+import pytest
+
+from .test_ext_autodoc import do_autodoc
+
+
+@pytest.mark.sphinx('html', testroot='ext-autodoc')
+def test_meta_public_doc_comment(app):
+    options = {"members": None}
+    actual = do_autodoc(app, 'module', 'target.meta_doc_comments', options)
+    assert '.. py:data:: _foo' in list(actual)