Maniphest T84320

Too long icon lists in the Python API documentation
Closed, Duplicate

Assigned To
None
Authored By
Roman Markov (unwave)
Jan 2 2021, 11:10 AM
Tags
  • Documentation
Subscribers
Aaron Carlisle (Blendify)
Robert Guetzkow (rjg)
Roman Markov (unwave)

Description

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();
        }
    }

Event Timeline

Roman Markov (unwave) created this task.Jan 2 2021, 11:10 AM
Robert Guetzkow (rjg) added a subscriber: Robert Guetzkow (rjg).Jan 2 2021, 2:27 PM

@Roman Markov (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 (rjg) closed this task as a duplicate of T76453: Some args/props in the API docs take *so much* space.Jan 2 2021, 3:45 PM
Roman Markov (unwave) added a comment.Jan 2 2021, 4:24 PM

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:

  1. https://docs.wxpython.org/gallery.html
  2. https://python-gtk-3-tutorial.readthedocs.io/en/latest/gallery.html
  3. 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 (rjg) added a subscriber: Aaron Carlisle (Blendify).Jan 2 2021, 4:27 PM

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