Too long icon lists in the Python API documentation #84320

New Issue

Roman Markov · 2021-01-02T11:10:57+01:00

Roman Markov commented

2021-01-02 11:10:57 +01:00

https://docs.blender.org/api/current/bpy.types.UILayout.html

The icon lists take too much space on this page, making it difficult to navigate.

They repeat 12 times and take:

81% of the characters
66% of the words
54% of the lines

I have to use this javascript before I can look something up. The Icon Viewer is the way to look for icons.

var paragraphs = document.getElementsByTagName('p');

for (let paragraph of paragraphs) {
var result = paragraph.innerHTML.search("TRACKING_CLEAR_FORWARDS'");
if (result != -1){
paragraph.remove();
}
}

https://docs.blender.org/api/current/bpy.types.UILayout.html The icon lists take too much space on this page, making it difficult to navigate. They repeat 12 times and take: - 81% of the characters - 66% of the words - 54% of the lines I have to use this javascript before I can look something up. The [Icon Viewer ](https://docs.blender.org/manual/en/latest/addons/development/icon_viewer.html) is the way to look for icons. ```lang=javascript var paragraphs = document.getElementsByTagName('p'); ``` for (let paragraph of paragraphs) { var result = paragraph.innerHTML.search("TRACKING_CLEAR_FORWARDS'"); if (result != -1){ paragraph.remove(); } } ```

Roman Markov commented

2021-01-02 11:10:57 +01:00

Added subscriber: @unwave

Robert Guetzkow commented

2021-01-02 14:27:21 +01:00

Added subscriber: @rjg

Robert Guetzkow commented

2021-01-02 14:27:21 +01:00

@unwave The API docs are meant to document possible parameter choices. While the way it currently displays the information may not be ideal, it certainly shouldn't be removed.

Robert Guetzkow commented

2021-01-02 15:45:50 +01:00

Closed as duplicate of #76453

Robert Guetzkow closed this issue

2021-01-02 15:45:50 +01:00

Roman Markov commented

2021-01-02 16:24:40 +01:00

I would suggest making them collapsible if it is a principle, as a limitation of auto-generated documentation. But for me, it is better to write that the parameter takes an icon sting id and add a link to a page with all the icons with the images of them, like this . Those name lists are practically useless and lower readability of other possible parameter choices. I think icons should be an exception.

Also, the documentation lacks a widget gallery.
Like these:

https://doc.qt.io/qt-5/gallery.html

Even a dirty one will benefit it a lot. A GUI documentation needs imagery, thus demands to be built differently than just a text.

I would suggest making them collapsible if it is a principle, as a limitation of auto-generated documentation. But for me, it is better to write that the parameter takes an icon sting id and add a link to a page with all the icons with the images of them, like [this ](https://wxpython.org/Phoenix/docs/html/stock_items.html). Those name lists are practically useless and lower readability of other possible parameter choices. I think icons should be an exception. Also, the documentation lacks a widget gallery. Like these: - https://docs.wxpython.org/gallery.html - https://python-gtk-3-tutorial.readthedocs.io/en/latest/gallery.html # https://doc.qt.io/qt-5/gallery.html Even a dirty one will benefit it a lot. A GUI documentation needs imagery, thus demands to be built differently than just a text.

Robert Guetzkow commented

2021-01-02 16:27:25 +01:00

Added subscriber: @Blendify

Robert Guetzkow commented

2021-01-02 16:27:25 +01:00

I agree with your suggestions, but that decision has to be made by @Blendify

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

Too long icon lists in the Python API documentation #84320

https://doc.qt.io/qt-5/gallery.html