[Bf-committers] Copy Data Path and API doc organization

[Bastien Montagne]

Hi,

Well, I wouldn’t see me as a « hard core master of Blender », but I find 
the bpy doc quite understandable, once you have grasped the basics of 
bpy (and learned how to read API doc?)…

As the page shown when clicking on the “view doc” states, resolution_x 
is a property of RenderSetting class, which *inherits* from that 
“virtual” bpy_struct class, as anything in bpy (a bit like normal Python 
classes inherit from “virtual” object class).

At the bottom of that same RenderSettings page (as for any other page of 
types section), you have the “References” part, which lists all places 
where RenderSettings instances are used… You can see that it’s only used 
by Scene class, as the “render” var!

So, yes, bpy introduces kind of a strongly typed behavior in Python (as 
most of the C→Python glue codes do, IMHO), but that’s all…

One in all, the bpy doc system is far from perfect (do you know anything 
even near from perfection?), but once you have taken the time to 
understand it (which isn’t so hard, really), I find it quite useful and 
powerful :)

Cheers,
Bastien

On Thu, 19 May 2011 09:31:39 , Damir Prebeg <blend.factory at gmail.com> wrote:
> Hi there,
>
> It would be much more useful if we could copy full data path and not
> just the last part of it. For instance, If I copy data path of x
> render resolution, all I get is "render.resolution_x". And under witch
> module or class lives that render? It's like you are giving me a
> street name with a number but you don't want to tell me in witch city
> that street is located.
> IMO, that string should look like this: bpy.context.scene.render.resolution_x.
> And in the tool tip for the same field I see "Python:
> RenderSettings.resolution_x". WTH... What RenderSettings? Where can I
> fin them?
>
> Click on view docs will take me to doc page where I see what
> resolution_x represents and that's nice info. But again, under witch
> class resolution_x is located? Logic tells me that parent class of
> resolution_x is stated on top of that page. And what I find there is
> that base class of resolution_x is bpy_struct because it clearly says:
> base class - bpy_struct ?!?
> And on the page of bpy_struct I get this info: "Note that
> bpy.types.bpy_struct is not actually available from within blender, it
> only exists for the purpose of documentation". WTH?!?!  And how TH can
> I get that freaking resolution_x when that bpy_struct thing isn't
> available?
>
> Just caricaturing but all the same...
>
> I'm sorry to say but IMO old API docs has been more useful (especially
> to beginners) than current ability to get docs directly from Blender.
> It's nice to know that resolution_x is part of RenderSettings class
> but that's quite useless since it's not clearly stated that render is
> off RenderSettings class and that render is located under
> bpy.context.scene.
>
> I'm sure that current doc organization is logic and readable to
> developers and hard core masters of Blender (like Bassam (-:) but for
> the rest of us, that's just another Blender's labyrinth...
>
> Best regards,
>
> Damir