Update python API documentation to use double quotes for strings and single quotes for enums #97464

New Issue

Novice · 2022-04-20T11:04:22+02:00

Novice commented

2022-04-20 11:04:22 +02:00

In python API documentation in many places there are single quotes for strings.
Like UILayout.prop
prop(data, property, text='', text_ctxt='', translate=True, icon='NONE', expand=False, slider=False, toggle=- 1, icon_only=False, event=False, full_event=False, emboss=True, index=- 1, icon_value=0, invert_checkbox=False)

text (string, (optional)) – Override automatic text of the item
text_ctxt (string, (optional)) – Override automatic translation context of the given text
translate (boolean, (optional)) – Translate the given text, when UI translation is enabled
icon (enum in ['NONE', ...

Some use double quotes for strings UILayout.prop_with_popover
prop_with_popover(data, property,text="", text_ctxt="", translate=True, icon='NONE', icon_only=False, panel)

Since Best Practice: Conventions to follow for writing good scripts says "Use single quotes for enums, and double quotes for strings", I think it would look better if the documentation used double quotes for strings and single quotes only for enums.

Unless there is a reason why it's preferred to use single quotes for strings in prop but not prop_with_popover, which I may have missed.

(If someone reads this. Where is the python API documentation? I followed the guide Documentation project to get the documentation but couldn't find python API docs in there.)

In python API documentation in many places there are single quotes for strings. Like [UILayout.prop ](https://docs.blender.org/api/current/bpy.types.UILayout.html?highlight=layout%20prop#bpy.types.UILayout.prop) prop(data, property, **text=''**, **text_ctxt=''**, translate=True, icon='NONE', expand=False, slider=False, toggle=- 1, icon_only=False, event=False, full_event=False, emboss=True, index=- 1, icon_value=0, invert_checkbox=False) - text (**string**, (optional)) – Override automatic text of the item - text_ctxt (**string**, (optional)) – Override automatic translation context of the given text - translate (boolean, (optional)) – Translate the given text, when UI translation is enabled - icon (enum in ['NONE', ... Some use double quotes for strings [UILayout.prop_with_popover ](https://docs.blender.org/api/current/bpy.types.UILayout.html?highlight=layout%20prop_with_popover#bpy.types.UILayout.prop_with_popover) prop_with_popover(data, property,**text=""**, **text_ctxt=""**, translate=True, icon='NONE', icon_only=False, panel) Since [Best Practice: Conventions to follow for writing good scripts ](https://docs.blender.org/api/current/info_best_practice.html) says "Use single quotes for enums, and double quotes for strings", I think it would look better if the documentation used double quotes for strings and single quotes only for enums. Unless there is a reason why it's preferred to use single quotes for strings in prop but not prop_with_popover, which I may have missed. (If someone reads this. Where is the python API documentation? I followed the guide [Documentation project ](https://developer.blender.org/project/view/53/) to get the documentation but couldn't find python API docs in there.)

Novice commented

2022-04-20 11:04:22 +02:00

Added subscriber: @BlenderAmateur

Richard Antalik commented

2022-06-08 19:04:08 +02:00

Added subscriber: @iss

Richard Antalik commented

2022-06-08 19:04:08 +02:00

This documentation is mostly automatically generated, though there is some hand written content. when you clone Blender git repo, it can be found in doc\python_api\ and it is generated by running sphinx_doc_gen.py

To actual report - I am not sure how some properties use single and other double quotes, will have to check this, but since these are automatically generated, I would assume this stems from RNA property definitions so it's likely, that there is reason for this.

This documentation is mostly automatically generated, though there is some hand written content. when you clone Blender git repo, it can be found in `doc\python_api\` and it is generated by running `sphinx_doc_gen.py` To actual report - I am not sure how some properties use single and other double quotes, will have to check this, but since these are automatically generated, I would assume this stems from RNA property definitions so it's likely, that there is reason for this.

Aaron Carlisle commented

2022-11-03 21:40:45 +01:00

Changed status from 'Needs Triage' to: 'Confirmed'