diff options
author | Campbell Barton <campbell@blender.org> | 2022-05-25 06:39:47 +0300 |
---|---|---|
committer | Campbell Barton <campbell@blender.org> | 2022-05-25 06:43:01 +0300 |
commit | 57b87feda1527d86f06121105992ee52355fd160 (patch) | |
tree | e8c98a684d371a2dcae4461bfc799f96011b4570 /doc | |
parent | d46647040d91c68bc8089b3c0b392d89a1bba4a6 (diff) |
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.
Diffstat (limited to 'doc')
-rw-r--r-- | doc/python_api/sphinx_doc_gen.py | 33 |
1 files changed, 30 insertions, 3 deletions
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") |