Suggestion for API function template

[jmv]

Hello,

This is my very first post here, and I don’t know if I’m in the right place?

I discovered programming with blender. So my best friend is the API documentation. it is very good, there is all the info.
However the function declarations and the comments of the parameters are enormously compressed.
This makes it difficult to find information when there are many parameters.

For example, for a function like “bpy.ops.export_scene.fbx”, the area displayed on my desktop computer is barely 10% of the screen size.

There is also double scrolling, that of the argument list and that of the page itself, which makes navigation sometimes surprising.

(For this point, I was able to download the documentation in html and disabled the line 5 “max-height: 245px;” of “css / theme_overrides.css”)

However, I don’t know how to modify the template.

I would like to suggest these few points to improve reading:

• have a more “responsive” page (in yellow)
• (and or) Do not lose an entire column reserved for the label “Parameters:” (in green)
• (and/or) Place the default values ​​with the list of parameters rather than in a mono-block without space (in light blue)
• (and/or)Do not have the list of parameters in a scrollable box. if not have the possibility of unfolding it.

I hope this will help improve the arrival of a novice like me.
Thanks for what you do.
jmv.

[jmv]

[Update]
I managed to get a full page by adding:

.wy-nav-content { max-width: none !important; }

at the end of the file “css / theme_overrides.css”
I get a much larger but much more readable page

[testure]

I agree, this has always been a bit annoying. As somebody with a 4k monitor, it’s even worse- akin to reading a mobile page on my TV.

From your screenshot it also looks like you also have:

td.field-body { max-height: none !important; }

[jmv]

Yes ! sorry,
here is the file “theme_overrides.css”

/* Prevent Long enum lists */
.field-body {
   display: block;
   width: 100%;
   /*REMOVED max-height: 245px;*/
   /*ADDED*/ max-height: auto !important;
   overflow-y: auto !important;
}

/* Hide home icon in search area */
.wy-side-nav-search > a:hover {background: none; opacity: 0.9}
.wy-side-nav-search > a.icon::before {content: none}

/*ADDED*/ .wy-nav-content { max-width: none !important; }

[Blendify]

While it is easy to fix in some senses what happens for people who have huge 32:9 aspect ratio monitors. At that point, a whole paragraph would only take up one line which hurts readability. So a proper solution would account for this as well. I would be in favor of making the content a little bit wider but don’t want to go to .wy-nav-content { max-width: none !important; }.

I created https://developer.blender.org/T73223 and will try to get to it before 2.83.

[Blendify]

You can suggest some of these changes here also: https://github.com/readthedocs/sphinx_rtd_theme

[testure]

isn’t solving display edge cases like this what frameworks like Bootstrap were developed for?

anecdotally- anybody I’ve ever seen who uses a crazy ultrawide curved monitor is partitioning their screen space as if they had two or three monitors side by side. I can’t say I’ve ever seen a browser maximized to full screen on a display like that- but that doesn’t mean somebody out there isn’t doing it.

[jmv]

Personally, the width of the content area is a plus, but it’s not what makes it difficult for me to find information.
These are mainly the parameters in a scrollable list, there is no longer a question of whether they are readable or not, you have to go find them, hidden in their block.

[JonasPrintzen]

Hello @jmv!

I created a new task for this not long ago. I would be happy to get some
feedback from the initial work I started. I don’t pretend to be a visual style expert, my focus is actually on using doxygen to it’s full potential, which I have some professional experience with.

Tune in with T73149 (patch D6625) and let’s talk.

[jmv]

it would be with pleasure @JonasPrintzen

but I’m a novice with blender on the code side, and T73149 or D6625, it sounds to me the same way as
@_~#)=^^.

I looked at developer.blender.org and I found this https://developer.blender.org/T73140?

I don’t know how I can help, I don’t understand the git of blender (and git in general) …

I saw that you were making patches, but I can’t install them locally and try them out.

[Blendify]

Yes, however, the theme that we use is based on a very uncommon framework: https://github.com/snide/wyrm There is talk to move away from this / start a new theme but both are a lot of work. But might be something I may consider doing this summer.

[Blendify]

These are mainly the parameters in a scrollable list, there is no longer a question of whether they are readable or not, you have to go find them, hidden in their block.

The reason for this was to avoid ultra-long lists of parameters such as long lists of icons in https://docs.blender.org/api/2.82/bpy.types.UILayout.html

I am not a UI designer so if someone has better ideas they are always a consideration

[testure]

The reason for this was to avoid ultra-long lists of parameters such as long lists of icons in

Yeah, I could see that, although it’s not bad on my 4k monitor I could imagine it’s not great at 1080p. One possible solution would be to give lengthy property lists a special class that constrains it to a max-height (icons seem to be an outlier). At that point a scroll bar would be tolerable, but a better solution would be to have a “Show More” link at the bottom, and after clicking the rest would be visible. something like this:

[jmv]

Yes, indeed for the type UILayout, a complete list is not suitable.

The idea of testure seems to be a good compromise, however, automatic code generation is excellent for batch processing, and bad on a case-by-case basis.
Suddenly, we would have a “Show more” for all definitions.
Whereas with the current “max-height”, the browser chooses itself to display or not a scrollable list.

[testure]

with something like jquery though it’s fairly trivial and doesn’t require any type of change to automatic documentation. A simple selector like this would give you access to the problematic list items, and then you could do whatever you wanted with them (add a class, append new HTML, etc):

$("td.field-body li:contains('enum in [')").addClass('max_height_controlled')

[jmv]

Yes, with javascript, we can have anything we want.
You can also modify the entire structure inside the browser with a script.
But, if I’m not mistaken @Blendify , the documentation is intended to be a static site, to be viewed on small machines (tablet, laptop, smartphone)

[jmv]

If using a more complex Javascript script is not a barrier (?), this would resolve many situations

[testure]

But, if I’m not mistaken @Blendify , the documentation is intended to be a static site, to be viewed on small machines (tablet, laptop, smartphone)

looking at the source of the site right now and there are already 8 different JS files being imported (including jquery).

[jmv]

Yes I see.
This is the minimum for browser compatibility, navigation and the search bar,

note: your proposal is good.
but it is on a case by case basis. Like a bandage. Over time, we may end up with several different cases that change the whole appearance of the site.

[testure]

Like a bandage. Over time, we may end up with several different cases that change the whole appearance of the site

unfortunately this is a fundamental reality of web development, you have to decide if you want to solve edge cases or be satisfied with an imperfect result.