Blender 5.0 support

[Andrej730]

Wanted to create an issue to keep track of issues required to solve to support Blender 5.0.

Blender 5.0 pending changes:

• bpy.types.Context header - https://projects.blender.org/blender/blender/pulls/148813 (still required 5.0 backport - https://projects.blender.org/blender/blender/pulls/149304)
• missing enchant https://projects.blender.org/blender/blender/pulls/149174 (optional)
• bmesh.types - https://projects.blender.org/blender/blender/pulls/149179
• audaspace fix - https://projects.blender.org/blender/blender/pulls/149221
  submitted PR to upstream's upstream - Fix broken doc-string function argument type definition neXyon/audaspace#61
• substitution_definition problem - Update: Skip processing substitution_definition nodes #404 makes it non-blocking issue
• Some modules are moved to _ prefix (e.g. bl_i18n_utils -> _bl_i18n_utils) Fix: Support new private modules in Blender 5.0 #399 #400
• problem with handling important block in gpu.shader Update: add support for important nodes #402

[Andrej730]

subsituion_definition problem - somewhere in 5.0 new syntax for rst was introduced:

https://github.com/blender/blender/blob/73273618048c1ae3b9f3efe49bbeb94c661cd76f/source/blender/python/bmesh/bmesh_py_types.cc#L4850-L4866

Which breaks stubs generation. Not sure whether it's an issue upstream or our generator doesn't support substitution_definition nodes.

Error:

TypeError: <class 'docutils.nodes.substitution_definition'> must not be a child of <class 'docutils.nodes.document'>.
<document source="<string>">
    <source-filename>
        bmesh.types.rst
    <module>
        <name>
            bmesh.types
        <description>
    <substitution_definition names="UV_STICKY_SELECT_MODE_REF">
        (
        <class-ref>
            bpy.types.ToolSettings.uv_sticky_select_mode

[nutti]

bmesh.types - https://projects.blender.org/blender/blender/pulls/149175

This was handled by my PR.
https://projects.blender.org/blender/blender/pulls/149179

[nutti]

This was handled by my PR. https://projects.blender.org/blender/blender/pulls/149179

Closed my PR.

[Andrej730]

Submitted audaspace fix to Blender - https://projects.blender.org/blender/blender/pulls/149221

[nutti]

I think some issues can be ignored if it will raise error.
I want to make sure that below two will raise an error.
If not, we can skip these issues for now.

• substitution_definition problem
• problem with handling important block in gpu.shader

[Andrej730]

Another problem I've found is stubs generation fails processing .. important:: block in gpu.shader.

https://github.com/blender/blender/blob/0fe91bd2d97c5d43d6ec3d2814393297128c7f58/source/blender/python/gpu/gpu_py_shader.cc#L1064-L1066

Error:

Traceback (most recent call last):
  File "L:\Projects\Github\fake-bpy-module\src\gen.py", line 251, in <module>
    main()
  File "L:\Projects\Github\fake-bpy-module\src\gen.py", line 247, in main
    generate(rst_files, mod_files)
  File "L:\Projects\Github\fake-bpy-module\src\gen.py", line 60, in generate
    documents = fbm.transform(documents, mod_files)
                ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "L:\Projects\Github\fake-bpy-module\src\fake_bpy_module\transformer\transformer.py", line 61, in transform
    return t.transform(documents)
           ^^^^^^^^^^^^^^^^^^^^^^
  File "L:\Projects\Github\fake-bpy-module\src\fake_bpy_module\transformer\transformer.py", line 150, in transform
    transformer.apply(**apply_params)
  File "L:\Projects\Github\fake-bpy-module\src\fake_bpy_module\transformer\format_validator.py", line 263, in apply
    self._apply(document)
  File "L:\Projects\Github\fake-bpy-module\src\fake_bpy_module\transformer\format_validator.py", line 255, in _apply
    self._check_document(document)
  File "L:\Projects\Github\fake-bpy-module\src\fake_bpy_module\transformer\format_validator.py", line 251, in _check_document
    raise TypeError(f"{type(child)} must not be a child of "
TypeError: <class 'docutils.nodes.important'> must not be a child of <class 'docutils.nodes.document'>.

The good news is that it is the last error for 5.0, can confirm that if all errors listed in the first post are fixed, then build finished successfully.

[Andrej730]

I think some issues can be ignored if it will raise error. I want to make sure that below two will raise an error. If not, we can skip these issues for now.

• substitution_definition problem
• problem with handling important block in gpu.shader

It seems substitution_definition kind of work in general (was testing by adding one to code_document_node_translator_test\input\basic\basic.rst), but do not expand for function arguments description in particular - since we just convert it to text (detail_body.astext()), ignoring possible children substitute references.

For argument types DataTypeNode is used and it's using actual children references, therefore they're properly expanded later.

fake-bpy-module/src/fake_bpy_module/analyzer/directives.py

Lines 451 to 456 in 38e0ce3

	if detail_type in ("arg", "param"):
	arg_node.element(DescriptionNode).add_text(
	detail_body.astext())
	elif detail_type == "type":
	dtype = parse_data_type(detail_body)
	arg_node.element(DataTypeListNode).append_child(dtype)

@nutti

Do you think it's okay for now to just skip all substitution_definition children in the document after publish_doctree is done and add a warning that they were found and may not be handled properly? We'll need to skip them here either way - since their references are already expanded/discarded after publish_doctree, regardless whether we resolved their proper expansion in arg descriptons.

---

Implemented in #404

[Andrej730]

Can confirm that latest also works after these fixes.