blender
/
blender
129
397
Fork 571
Code Issues 6.2k Pull Requests 751 Projects 19 Wiki Activity

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.
This commit is contained in:
Campbell Barton 2022-05-25 13:39:47 +10:00
parent d46647040d
commit 57b87feda1
1 changed files with 30 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

33
doc/python_api/sphinx_doc_gen.py
View File

@ -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")