[Bf-blender-cvs] [57b87feda15] master: PyDoc: suppress duplicate object description warning
Campbell Barton
noreply at git.blender.org
Wed May 25 05:44:20 CEST 2022
Commit: 57b87feda1527d86f06121105992ee52355fd160
Author: Campbell Barton
Date: Wed May 25 13:39:47 2022 +1000
Branches: master
https://developer.blender.org/rB57b87feda1527d86f06121105992ee52355fd160
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.
===================================================================
M doc/python_api/sphinx_doc_gen.py
===================================================================
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")
More information about the Bf-blender-cvs
mailing list