RNA API: Add Optional API/Dev documentation #128531

New Issue

Bastien Montagne · 2024-10-03T12:47:54+02:00

Bastien Montagne commented

2024-10-03 12:47:54 +02:00

Currently, the 'tooltip' user-related info of all RNA structs, functions and properties also end up being used as technical documentation for the Python API.

Problem

While this works well (enough) in many cases, there are more complex and involved parts of RNA that could benefit from a better, more technical documentation. Currently it is always a balance game between what the regular user should see vs. what the python dev should know.

Having a dedicated API doc string would also allow for things like linking within the API doc.

Proposal

Add another optional technical_info member to our RNA struct, functions and properties. This will be used by the API doc generation tool.

These strings will not be translated.

Future Ideas

This info could maybe also be exposed directly from Blender UI (on an opt-in basis). Maybe in the UI tooltips, if the 'developers extra' option is enabled?

Currently, the 'tooltip' user-related info of all RNA structs, functions and properties also end up being used as technical documentation for the Python API. ## Problem While this works well (enough) in many cases, there are more complex and involved parts of RNA that could benefit from a better, more technical documentation. Currently it is always a balance game between what the regular user should see vs. what the python dev should know. Having a dedicated API doc string would also allow for things like linking within the API doc. ## Proposal Add another optional `technical_info` member to our RNA struct, functions and properties. This will be used by the API doc generation tool. These strings will not be translated. ## Future Ideas This info could maybe also be exposed directly from Blender UI (on an opt-in basis). Maybe in the UI tooltips, if the 'developers extra' option is enabled?

Bastien Montagne added the

Type

Design

label 2024-10-03 12:47:54 +02:00

Bastien Montagne added this to the Core project 2024-10-03 12:47:54 +02:00

Bastien Montagne commented

2024-10-03 12:48:11 +02:00

CC @Sergey @ideasman42 @dr.sybren

Sergey Sharybin commented

2024-10-04 12:01:49 +02:00

I don't see anything wrong about this proposal, but it would be good to have an example of such technical_info to understand it a bit better.
The part of a more comprehensive API docs it's definitely a great addition.

The part I am not sure is showing it in a tooltip for developers-extra. Some thoughts about it:

If the information is crucial for understanding what property actually means, it seems strange to hide such information from non-technical users.
You could imagine some formatting in the description would bring clarity: i.e. ability to use formulas. If the field is used for API docs it seems easy to support. Showing such things in a tooltip could be problematic.

I don't see anything wrong about this proposal, but it would be good to have an example of such `technical_info` to understand it a bit better. The part of a more comprehensive API docs it's definitely a great addition. The part I am not sure is showing it in a tooltip for developers-extra. Some thoughts about it: - If the information is crucial for understanding what property actually means, it seems strange to hide such information from non-technical users. - You could imagine some formatting in the description would bring clarity: i.e. ability to use formulas. If the field is used for API docs it seems easy to support. Showing such things in a tooltip could be problematic.

Bastien Montagne commented

2024-10-04 17:50:03 +02:00

I think @dr.sybren had specific examples in mind related to the new animation system?

The part I am not sure is showing it in a tooltip for developers-extra. Some thoughts about it:

If the information is crucial for understanding what property actually means, it seems strange to hide such information from non-technical users.

In such case the information should indeed be in the regular tooltip, and not in the new proposed technical_info one.

You could imagine some formatting in the description would bring clarity: i.e. ability to use formulas. If the field is used for API docs it seems easy to support. Showing such things in a tooltip could be problematic.

This is a fair point. On the other end, showing it in the tooltips allow some sort of inlined API doc, even if it may render weird/badly in case advanced features like links or formulas are used.

I think @dr.sybren had specific examples in mind related to the new animation system? > The part I am not sure is showing it in a tooltip for developers-extra. Some thoughts about it: > * If the information is crucial for understanding what property actually means, it seems strange to hide such information from non-technical users. In such case the information should indeed be in the regular tooltip, and not in the new proposed `technical_info` one. > * You could imagine some formatting in the description would bring clarity: i.e. ability to use formulas. If the field is used for API docs it seems easy to support. Showing such things in a tooltip could be problematic. This is a fair point. On the other end, showing it in the tooltips allow some sort of `inlined` API doc, even if it may render weird/badly in case advanced features like links or formulas are used.

Sybren A. Stüvel commented

2024-10-07 18:37:43 +02:00

It might make it harder to write good documentation if it has to be readable both in the HTML API docs and in the developer tooltips. I'd propose just keeping things simple, writing the text for the HTML docs. Once its use has grown a bit, and we have a bunch of concrete examples, we can always take a look at how they read as tooltips.

I think @dr.sybren had specific examples in mind related to the new animation system?

This could already be simple stuff, like animation_data.action_slot_name could have:

This value can be used as key of the animation_data.action.slots collection property, but using animation_data.action_slot is preferred as it is more efficient.

That kind of information I wouldn't put into a regular tooltip.

Update: Another simple example would be the documentation for context.active_object, where you could add to the techincal info that in order to actually set what is the active object, you'd set context.view_layer.objects.active. There's more places where I'd liked to have such a field in the past, but I don't know those from the top of my head any more.

It might make it harder to write good documentation if it has to be readable both in the HTML API docs and in the developer tooltips. I'd propose just keeping things simple, writing the text for the HTML docs. Once its use has grown a bit, and we have a bunch of concrete examples, we can always take a look at how they read as tooltips. > I think @dr.sybren had specific examples in mind related to the new animation system? This could already be simple stuff, like `animation_data.action_slot_name` could have: > This value can be used as key of the `animation_data.action.slots` collection property, but using `animation_data.action_slot` is preferred as it is more efficient. That kind of information I wouldn't put into a regular tooltip. **Update:** Another simple example would be the documentation for `context.active_object`, where you could add to the techincal info that in order to actually set what is the active object, you'd set `context.view_layer.objects.active`. There's more places where I'd liked to have such a field in the past, but I don't know those from the top of my head any more.

Sergey Sharybin commented

2024-10-09 16:51:45 +02:00

Properties from the example are about properties that are not exposed to the interface, so the part of the proposal about tooltip is not really applicable? Maybe there could be a way to more easily switch from python docstring to API manual (similar to the Online Manual which we have for properties in UI)?

Sybren A. Stüvel commented

2024-10-10 11:53:04 +02:00

Properties from the example are about properties that are not exposed to the interface, so the part of the proposal about tooltip is not really applicable?

Still I think can be good to have "user explanation" and "developer explanation" fields.

While I'm writing RNA wrappers, I'm often thinking of more developer-centric info, and having a place to put that would be quite nice.

Also it'll lower the barrier for documenting things for developers, because you know that that info will never make it to the regular UI. Having to first search the UI code to see if some property is ever shown somewhere or not, before you can write docs, is IMO not something people should have to do. And in a similar fashion, the decision to show some property in the UI should not have to be preceeded by checking its tooltip description, to see whether that was used for developer-centric info (because it was written before the property was shown in the UI).

Maybe there could be a way to more easily switch from python docstring to API manual (similar to the Online Manual which we have for properties in UI)?

Not sure what you mean with this, or what the implications would be of me answering "yes" or "no" here.

> Properties from the example are about properties that are not exposed to the interface, so the part of the proposal about tooltip is not really applicable? Still I think can be good to have "user explanation" and "developer explanation" fields. While I'm writing RNA wrappers, I'm often thinking of more developer-centric info, and having a place to put that would be quite nice. Also it'll lower the barrier for documenting things for developers, because you _know_ that that info will never make it to the regular UI. Having to first search the UI code to see if some property is ever shown somewhere or not, before you can write docs, is IMO not something people should have to do. And in a similar fashion, the decision to show some property in the UI should not have to be preceeded by checking its tooltip description, to see whether that was used for developer-centric info (because it was written before the property was shown in the UI). > Maybe there could be a way to more easily switch from python docstring to API manual (similar to the Online Manual which we have for properties in UI)? Not sure what you mean with this, or what the implications would be of me answering "yes" or "no" here.

Nathan Vegdahl commented

2024-10-10 16:18:41 +02:00

I generally agree with this proposal.

For context, @dr.sybren and I discussed this in person before he brought it up with @mont29, ultimately resulting in this proposal. Here is my own motivation for wanting this:

From a user perspective, my motivating experience is the countless times I've been working on scripts or addons, and the documentation for a type, function, or operator in the Python API reference is a one-liner that just doesn't provide all the information I need (e.g. corner cases, error conditions, specifics of the algorithm used, invariants that are expected/upheld, whether it requires being in a particular mode, etc.). Verifying these kinds of things experimentally or by diving into Blender's source code is not only inconvenient, but also sometimes leaves me wondering whether the behavior I discovered is actually intentional or not.

From a Blender developer perspective, my motivating experience has been working on the new animation system and wanting to write thorough Python API documentation for it, but having no clear place to do that. Therefore I don't write it and instead just fill out the tooltip in the vague hope that it's enough (and sometimes with awkward wording due to trying to cram in as much info as I can).

I have a strong suspicion that the latter experience is a primary cause of the former. In practice, making it easy for devs to document their APIs is a prerequisite for them (us) actually doing so.

(I doubt anyone is in disagreement about this, but I wanted to outline it explicitly.)

Properties from the example are about properties that are not exposed to the interface, so the part of the proposal about tooltip is not really applicable?

It does seem likely that a lot of where we'll want to use this isn't in things that are directly exposed in the UI. Additionally, I think technical_info maybe isn't the best name for this, because to me this is more about API documentation, which isn't typically relevant when using something from the UI even when it is also exposed there.

Having said that, I do think there's a superset relationship here, where the technical API documentation is basically a superset of the UI-facing tooltip whenever there is one. So it might make sense to have the tooltip field double as the top summary line of the API documentation. That could also help keep the tooltips and API documentation from falling out of sync when both exist.

There may also be cases where there is additional technical documentation that's useful to e.g. advanced users from the UI. But it's also easy for this to get out of hand and get too complicated if we try to address too many things at once. Moreover, I can't recall a time where I felt like a tooltip wasn't enough (due to lack of space for text, at least). Whereas I constantly run into lacking Python API docs. So I think it's better to keep things simple and focus on the latter for now.

I generally agree with this proposal. For context, @dr.sybren and I discussed this in person before he brought it up with @mont29, ultimately resulting in this proposal. Here is my own motivation for wanting this: From a user perspective, my motivating experience is the countless times I've been working on scripts or addons, and the documentation for a type, function, or operator in the Python API reference is a one-liner that just doesn't provide all the information I need (e.g. corner cases, error conditions, specifics of the algorithm used, invariants that are expected/upheld, whether it requires being in a particular mode, etc.). Verifying these kinds of things experimentally or by diving into Blender's source code is not only inconvenient, but also sometimes leaves me wondering whether the behavior I discovered [is actually intentional or not](https://xkcd.com/1172/). From a Blender developer perspective, my motivating experience has been working on the new animation system and wanting to write thorough Python API documentation for it, but having no clear place to do that. Therefore I don't write it and instead just fill out the tooltip in the vague hope that it's enough (and sometimes with awkward wording due to trying to cram in as much info as I can). I have a strong suspicion that the latter experience is a primary cause of the former. In practice, making it easy for devs to document their APIs is a prerequisite for them (us) actually doing so. (I doubt anyone is in disagreement about this, but I wanted to outline it explicitly.) > Properties from the example are about properties that are not exposed to the interface, so the part of the proposal about tooltip is not really applicable? It does seem likely that a lot of where we'll want to use this isn't in things that are directly exposed in the UI. Additionally, I think `technical_info` maybe isn't the best name for this, because to me this is more about API documentation, which isn't typically relevant when using something from the UI even when it is also exposed there. Having said that, I do think there's a superset relationship here, where the technical API documentation is basically a superset of the UI-facing tooltip whenever there is one. So it might make sense to have the tooltip field double as the top summary line of the API documentation. That could also help keep the tooltips and API documentation from falling out of sync when both exist. There may *also* be cases where there is additional technical documentation that's useful to e.g. advanced users from the UI. But it's also easy for this to get out of hand and get too complicated if we try to address too many things at once. Moreover, I can't recall a time where I felt like a tooltip wasn't enough (due to lack of space for text, at least). Whereas I constantly run into lacking Python API docs. So I think it's better to keep things simple and focus on the latter for now.

Sergey Sharybin commented

2024-10-10 17:39:36 +02:00

Still I think can be good to have "user explanation" and "developer explanation" fields.
While I'm writing RNA wrappers, I'm often thinking of more developer-centric info, and having a place to put that would be quite nice.

Sure, but it is slightly different from the current state of the proposal, which explicitly mentions showing the fields in the UI tooltip.

For adding more documentation for properties: huge +1
For making it easier to add documentation: also huge +1
For showing this extra information in a tooltip: I am not convinced form the current examples. There might be other cases where it is very useful, but I am failing to think of something concrete atm. That being said, I think we should be carful of what we expose in the interface, and how we present "regular" tooltips.

Not sure what you mean with this, or what the implications would be of me answering "yes" or "no" here.

For the properties in the UI you can right click -> Online Manual. It will give you (hopefully) fuller explanation of what it does. This feels quite intuitive way of obtaining extra information for cases when something is super clear from the tooltip.

For the properties that are not exposed to the UI there is no way to click on the Online Manual, and the docstring might not have enough of visual capabilities to properly describe certain things. So it was a though that maybe implementing something similar to Online Manual will give ability to present docstring in a nice format, possibly with images (although, images is not something that is easy to reference from a technical_info type of an RNA field).

> Still I think can be good to have "user explanation" and "developer explanation" fields. > While I'm writing RNA wrappers, I'm often thinking of more developer-centric info, and having a place to put that would be quite nice. Sure, but it is slightly different from the current state of the proposal, which explicitly mentions showing the fields in the UI tooltip. For adding more documentation for properties: huge +1 For making it easier to add documentation: also huge +1 For showing this extra information in a tooltip: I am not convinced form the current examples. There might be other cases where it is very useful, but I am failing to think of something concrete atm. That being said, I think we should be carful of what we expose in the interface, and how we present "regular" tooltips. > Not sure what you mean with this, or what the implications would be of me answering "yes" or "no" here. For the properties in the UI you can right click -> Online Manual. It will give you (hopefully) fuller explanation of what it does. This feels quite intuitive way of obtaining extra information for cases when something is super clear from the tooltip. For the properties that are not exposed to the UI there is no way to click on the Online Manual, and the docstring might not have enough of visual capabilities to properly describe certain things. So it was a though that maybe implementing something similar to Online Manual will give ability to present docstring in a nice format, possibly with images (although, images is not something that is easy to reference from a `technical_info` type of an RNA field).

👍 1

Bastien Montagne referenced this issue

2024-10-18 11:52:53 +02:00

Add Clarifying language around PointerProperty Class and Function name similarities #129141

Bastien Montagne commented

2024-10-18 12:10:36 +02:00

Note that we already have a right-click option to go to the Online Python Reference documentation from properties exposed in the UI.

I think it would help 'in general' to have this extra info in tooltips when 'developers extra' is enabled, even though for sure it might not always be the best formatting etc. Again, this would not be exposed to regular users anyway.

But I don't have strong opinion about it either, so if this is controversial we can just keep it out of the initial deliverable, and re-evaluate it later.

Note that we already have a right-click option to go to the `Online Python Reference` documentation from properties exposed in the UI. I think it would help 'in general' to have this extra info in tooltips when 'developers extra' is enabled, even though for sure it might not _always_ be the best formatting etc. Again, this would not be exposed to regular users anyway. But I don't have strong opinion about it either, so if this is controversial we can just keep it out of the initial deliverable, and re-evaluate it later.

👍 1

Sybren A. Stüvel commented

2024-10-29 10:42:49 +01:00

we can just keep it out of the initial deliverable, and re-evaluate it later.

I think that's a good idea.

> we can just keep it out of the initial deliverable, and re-evaluate it later. I think that's a good idea.

👍 1

Sign in to join this conversation.

No Label

Download

What's New

Blender Studio

Manual

Developers Blog

Documentation

Benchmark

Blender Conference

Development Fund

One-time Donations

RNA API: Add Optional API/Dev documentation #128531

Problem

Proposal

Future Ideas