From 57b87feda1527d86f06121105992ee52355fd160 Mon Sep 17 00:00:00 2001
From: Campbell Barton <campbell@blender.org>
Date: Wed, 25 May 2022 13:39:47 +1000
Subject: PyDoc: suppress duplicate object description warning

RenderEngine.render is both a method and an attribute,
while this should be avoided it's not causing a problem in practice
so quiet the warning when generating docs.

Sphinx now builds docs without any warnings.
---
 doc/python_api/sphinx_doc_gen.py | 33 ++++++++++++++++++++++++++++++---
 1 file changed, 30 insertions(+), 3 deletions(-)

(limited to 'doc/python_api')

diff --git a/doc/python_api/sphinx_doc_gen.py b/doc/python_api/sphinx_doc_gen.py
index be94a54b24c..b29251b67cc 100644
--- a/doc/python_api/sphinx_doc_gen.py
+++ b/doc/python_api/sphinx_doc_gen.py
@@ -372,6 +372,23 @@ RNA_BLACKLIST = {
     "PreferencesSystem": {"language", }
 }
 
+# Support suppressing errors when attributes collide with methods,
+# use `noindex` on the attributes / data declarations.
+#
+# NOTE: in general this should be avoided but changing it would break the API,
+# so explicitly suppress warnings instead.
+#
+# NOTE: Currently some API generation doesn't support this is it is not used yet,
+# see references to `RST_NOINDEX_ATTR` in code comments.
+#
+# A set of tuple identifiers: `(module, type, attr)`.
+RST_NOINDEX_ATTR = {
+    # Render is both a method and an attribute, from looking into this
+    # having both doesn't cause problems in practice since the `render` method
+    # is registered and called from C code where the attribute is accessed from the instance.
+    ("bpy.types", "RenderEngine", "render"),
+}
+
 MODULE_GROUPING = {
     "bmesh.types": (
         ("Base Mesh Type", "-"),
@@ -747,10 +764,12 @@ def py_descr2sphinx(ident, fw, descr, module_name, type_name, identifier):
 
     if type(descr) == GetSetDescriptorType:
         fw(ident + ".. attribute:: %s\n\n" % identifier)
+        # NOTE: `RST_NOINDEX_ATTR` currently not supported (as it's not used).
         write_indented_lines(ident + "   ", fw, doc, False)
         fw("\n")
     elif type(descr) == MemberDescriptorType:  # same as above but use "data"
         fw(ident + ".. data:: %s\n\n" % identifier)
+        # NOTE: `RST_NOINDEX_ATTR` currently not supported (as it's not used).
         write_indented_lines(ident + "   ", fw, doc, False)
         fw("\n")
     elif type(descr) in {MethodDescriptorType, ClassMethodDescriptorType}:
@@ -793,6 +812,8 @@ def pyprop2sphinx(ident, fw, identifier, py_prop):
         fw(ident + ".. data:: %s\n\n" % identifier)
     else:
         fw(ident + ".. attribute:: %s\n\n" % identifier)
+
+    # NOTE: `RST_NOINDEX_ATTR` currently not supported (as it's not used).
     write_indented_lines(ident + "   ", fw, py_prop.__doc__)
     fw("\n")
     if py_prop.fset is None:
@@ -1445,17 +1466,23 @@ def pyrna2sphinx(basepath):
         struct_blacklist = RNA_BLACKLIST.get(struct_id, ())
 
         for prop in sorted_struct_properties:
+            identifier = prop.identifier
 
             # Support blacklisting props.
-            if prop.identifier in struct_blacklist:
+            if identifier in struct_blacklist:
                 continue
 
             type_descr = prop.get_type_description(class_fmt=":class:`%s`", collection_id=_BPY_PROP_COLLECTION_ID)
             # Read-only properties use "data" directive, variables properties use "attribute" directive.
             if "readonly" in type_descr:
-                fw("   .. data:: %s\n\n" % prop.identifier)
+                fw("   .. data:: %s\n" % identifier)
             else:
-                fw("   .. attribute:: %s\n\n" % prop.identifier)
+                fw("   .. attribute:: %s\n" % identifier)
+            # Also write `noindex` on requerst.
+            if ("bpy.types", struct_id, identifier) in RST_NOINDEX_ATTR:
+                fw("      :noindex:\n")
+            fw("\n")
+
             if prop.description:
                 write_indented_lines("      ", fw, prop.description, False)
                 fw("\n")
-- 
cgit v1.2.3