Docs: UI elements -> Blender Python API - mapping

It would be nice if there is a visual reference/tutorial that shows which Blender UI elements to which Python API corresponds.
This is not really enough: https://docs.blender.org/manual/en/latest/interface/window_system/tabs_panels.html

2 Likes

Yea these are frequent enough concerns to deserve an scope defining primer.

On what level would you want this mapping, UI panel to Python class/file that implements it? Or on the level of individual controls within a panel? For the latter, I assume you know about the Python tooltips?

Did you activate “Python Tooltips” in Blender preferences ?


jmv

1 Like

Python Tooltips are a great suggestion. There are occasional operations or tools that don’t have tooltips or print the wrong command to the console.

For example, here is a question that was looking for BMesh. It seems like a lot of the fields in ‘edit mode’ don’t display tooltips - including those related to UV translation. That said, this could be just as easily attributed to class naming - here’s a discussion related to BMesh’s name.

Tooltips are nice, but I don’t think they were ever intended to be a ‘beginner friendly API documentation’, and treating them as such only exacerbates the problem beginners are going to have with understanding the API in general. They are certainly useful once you already know what you’re doing.

On the subject of edit mode tooltips- there’s a lot of boilerplate associated with doing anything in bmesh, a simple tooltip wouldn’t be able to convey enough information to get the point across and would only create more confusion- that’s what the API documentation and python templates are for.

that’s what the API documentation and python templates are for

It’s fine if this is the solution. But I’d encourage the community to further push for ‘beginner friendly API documentation.’ Modules such as BMesh or GL Draw certainly require more advanced understanding. But I’m not sure if it’s helpful to obscure their existence from those that are unfamiliar. It makes sense to me for there to be a beginner primer that says - hey if you want to control these aspects, these are the related modules - although, fair warning, they’re complex.

I would hardly consider GL or bmesh ‘beginner topics’.

Agreed - that’s not what I’m arguing

my point is that their existence is not obscured at all! It’s in the docs for anybody to see with VERY clear examples! a two second Google search would take you directly to the API docs, a tooltip floating in the editor is not going to solve whatever problem you are trying to solve.

I agree that a tool tip might not be the solution. I’m not advocating for any given solution - just trying to highlight a problem. Basically, modules that are named and described with in-language obscure themselves from people not in the know - even when they’re at the top of a search result. If we’d like to leave it that way, then it might help to have other avenues (such as a short description in a getting started article) to help point searchers in the right direction.

Rest assured, I searched the butts out of google and the docs before you helped me (thank you by the way, you’ve been godsend). But what is a BMesh? What is OpenGL? What are they typically used for? Are those answers apparent from their name? When I ask our Blender artists what they are, they say “Oh yeah, I’ve seen that around but I have no idea what it is.” And that’s because this is language specific to Blender developers. I’ve heard a lot of senior developers say it is difficult to think like a beginner again. Hi I’m a beginner telling you how the on-boarding pipeline looks - which a majority of the time is pretty great, but we shouldn’t shrug off the remaining bit.

When I ask our Blender artists what they are, they say “Oh yeah, I’ve seen that around but I have no idea what it is.

Wait… why does an artist care about bmesh or opengl in the first place? Where does this need for knowledge accessibility end? Do they need to know about pointer properties? How about the RNA system? Maybe the msgbus? If it’s someone who fancies themselves a Python developer I would expect a bare minimum of technical competency and the ability to perform some basic searching. This isn’t ‘shrugging off the remaining bit’, it’s pointing out that the ‘remaining bit’ is undefined and can literally be anything and is infinite.

@testure I’ve really appreciated your help these past few months. I’m sorry if I’ve caused trouble. I just like trying to improve documentation.

why does an artist care about bmesh or opengl in the first place

They wouldn’t, but they are aware of CGI industry terms and these were unfamiliar phrases. If a phrase doesn’t click for me (a developer) or them (industry SMEs), then I can deduce the language is specific to this community. Is that a bad thing? No. People are bound to establish language that is community specific. I just figured, this being an open source community, that identifying on-boarding sticking points and smoothing them out would be helpful.

I would expect a bare minimum of technical competency and the ability to perform some basic searching

That’s not fair. I spend multiple days, sometimes a full week intermittently searching for answers and trying out solutions before posting to this site or any stack-exchange. But congrats, you’re making me feel pretty stupid.

Where does this need for knowledge accessibility end? …the ‘remaining bit’ is undefined and can literally be anything and is infinite

You’ve successfully outlined that some of the ideas on this thread are too ambitious. Maybe small changes or hierarchical design could keep scope in check. That could mean renaming BMesh to BoundryMesh, adding a search tag like ‘user interface’ to OpenGL, or a passing reference in a getting started article. In other words, changes that would make the API more readable or additional breadcrumbs. Happy to get involved in the community if it’s welcoming.

I see this thread is getting a little fraught in its nature. It may be useful for ALL new developers and those wishing to work in areas they aren’t familiar with, to take a good look at some of the add-ons in the Blender Add-ons:

For Mac it is here:

Other flavours of OS will have it elsewhere, most of the code here is well documented with DocStrings and the like and is an excellent place to learn about how to construct a python macro, or add-on.

I agree that there are not many examples of how to get started, but then this would be a massive undertaking given the plethora of things you can do to customise Blender.

I struggled for a long while to implement Live MIDI input and to understand timers & handlers, it does not mean I am stupid, or that anyone thinks I am - I am an Authorised Committer to Blender BTW. It’s just that customising Blender is very complicated and it it often a good practice to try something simple to understand the principles, to work always from a terminal running Blender, so you see the errors more clearly and then to gradually increase the scope of your work. More importantly document what you did and how you did it for later referral.

I hope this is helpful, that was the intention.

Cheers, Clock.

1 Like