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?
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