Segment direct&inherited properties/methods in reference documentation to enhance readability

[himbeles]

Motivation

Proposal:
This PR segments the properties and methods in the documentation into direct class properties/methods first, then an “Inherited” subsection with bracketed gray notes on the originating class.
(At least for me) This significantly improves the readability of the reference documentation, surfacing the direct features, before the large amount of inherited ones which are common between most components.

See, for example, the first properties of ui.table

Before, they were interleaved with client, classes, etc.

Now, they are in a dedicated section directly after:

Implementation

Modification of website/documentation/reference.py where the ancestor classes - already part of mro -- are surfaced in the documentation markdown. Segmentation of properties and methods into direct and inherited ones is based on these values, too.

Progress

• I chose a meaningful title that completes the sentence: "If applied, this PR will..."
• The implementation is complete.
• Pytests have been added (or are not necessary).
• Documentation has been added (or is not necessary).

[evnchn]

Thanks @himbeles for your PR.

It is a good initiative, and I am in agreement to showing the inheritance.

But this makes the list even more unwieldy though (eyeball: +50% length increase?).

I have said somewhere that the binding methods are a bit long in the documentation, but never got around to fixing it. I think we can cherish this opportunity for the cleanup.

Idea: could a tabbed interface make it more clear? Inspiration from Quasar

[himbeles]

We could skip the markers per property in my PR. At least there would already be the segmentation into two categories. I think you would already gain a lot with this minor change. Unfortunately, I don't have the bandwidth to do something much more sophisticated, like the tabbed interface (which I like).

[evnchn]

Maybe I can make it tabbed. It might just work!

[himbeles]

On that note, the inherited props which are listed essentially on every component documentation page also mess with web search results.

Say you are searching for 'nicegui add_slot' on google. The first results tend to be a random list of components which all include the same documentation. Instead, you would hope to land on ui.element where the method is actually defined.

Perhaps there is a way here to fix this, e.g. with the tabbed interface where only the "main" tab is indexed per component...

[evnchn]

Indeed, hiding the inherited props in a (default-hidden) tab may help with indexing, but that's certainly not all we can do.

SEO has been a challenging topic. Let's have a review:

• on one hand, typical NiceGUI websites, not blessed by Google, simple gets "connection lost" from the body because of no JavaScript execution. While Server-Side Rendering by invoking NodeJS, Vue and Quasar for the HTML #4557 tried to solve it, it lead to many issues.
• on the other hand, for some reason the NiceGUI documentation website is fully SEO scannable despite needing JavaScript to render the content.
• nevertheless the SEO for the NiceGUI documentation is still not very good and so SEO optimization for the Documentation website #5308 tries to fix it, but we don't know what I am doing there is right or wrong because (1) I can't see the Google webmaster dashboard, (2) I don't want (yet) to pay for premium tools, and (3) I lack SEO expertise

If you want to help you can check out #5308 first. I have some ideas for reigniting #4557 without invoking nodejs but let's leave it for later.

[evnchn]

d33f251

Hmm not sure

[himbeles]

Hmm, I think this does not work really well:
Too cluttered, too many tabs, and the naming being the class name is too obscure for a casual users (in contrast to the labels in Quasar).
Compared to this implementation, I would prefer the flat list with subheaders I proposed initially (without the markers per entry).

A simple alternative to make the lists more manageable without introducing "handcrafted" category labels could be to have tabs for methods and properties, not for direct vs. inherited. Then within each tab, you'd have the flat list for direct members, followed by inherited members, as proposed by me.

What do you think?
In general, I think that this or the initial proposal is already a significant improvement. And we can still improve in further steps.

[himbeles]

Concerning SEO, I'm no expert either, unfortunately...

[evnchn]

I think the code for tabbed interface work on logic side, what is holding it back is UI design. It lacks visual distinctiveness and is a bit easy to miss, especially when an element only inherits.

We may need some (possibly long) time to work on it. The project will possibly be of scale similar to #5044.

And so, right now I think we can keep that commit's code safely somewhere while we roll it back.

For the vertical height issue, I think it's still a valid concern. Maybe the inheritance label can be shown on the right, so as to not consume more that what was originally there?

[himbeles]

Yes, my proposal was to skip these class inheritance markers per member completely. Just to keep the segmentation. But we can play with putting it right aligned ...

[evnchn]

https://gist.github.com/evnchn/35b4e68ef3e42776bc69c2578e16d2aa

Byebye d33f251

[evnchn]

I'm satisfied with this. How about you? Straight talk is welcome.

[falkoschindler]

My two cents:

• Let's be careful with tabs and other ways to hide parts of the content. It can prevent the user from searching with Ctrl-F on the page. And if they don't know if they are looking for a method or property, or where it is inherited from, they might not be able to find it without visiting each tab.
• The inheritance information could be displayed in form of a "family_history" icon with a tooltip showing the name of the corresponding class. This doesn't cost much space and might be good enough for most visitors.

[evnchn]

Fair point about suddenly introducing tabs and breaking Ctrl+F expectations. There are ways to circumvent (GitHub actions log view implements custom search when click Ctrl+F) but it'll be a lot of work (NiceGUI 4.0 documentation page refresh?)

family_history icon is a stroke of genius (didn't know there is this icon) but tooltip maybe not, because of accessibility. It is entirely not triggerable via keyboard (I think).

Anyways I hope my divider is enough space-saving already.

Bonus item for later: "Skip to main content" for NiceGUI documentation site?

[himbeles]

Hi @evnchn, I think I'd still prefer a single divider (or just header) between direct and all inherited props combined. The division into all of the parent classes makes it quite cluttered without providing much benefit. Particularly given the names of the parent classes without further explanation or linked definition of these classes...

[evnchn]

Ok no problem, but then do we sort by alphabetically (more like original code) or sort by inheritance then alphabetical (more like current code)?

[himbeles]

Added an icon to the header.
Could somehow not find "family_history".

[himbeles]

Let's keep it simple for now. I have a tendency of overengineering things, sorry for that 😭

can relate :)

[evnchn]

Looks better than family_history?

It's at https://fonts.google.com/icons?selected=Material+Symbols+Outlined:family_history:FILL@0;wght@400;GRAD@0;opsz@24&icon.query=family+h&icon.size=24&icon.color=%231f1f1f

Material Symbols, so do sym_o_family_history

[himbeles]

Both look good to me. Feel free to decide!

[evnchn]

@himbeles I don't think this is in-progress anymore? We are pretty done with it? Please 👍 if you agree.

[falkoschindler]

Thanks @himbeles and @evnchn for this contribution! It turned out rather nicely!

I just refactored the code a little, e.g. replacing tuples with a dataclass. And I felt like wrapping inherited attributes in expansion items that are open by default. This makes them appear less subtle and even allows to hide them to focus on native attributes.

Let's merge!

[evnchn]

Default-open expansion with a border is a good idea. Now it looks like this, for those playing at home.

While it works, I think the icon and "Inherited methods" should be some shade of gray instead of black. It's too dominant now. But it can be done later, and possibly after talking to some designer.

[falkoschindler]

the icon and "Inherited methods" should be some shade of gray instead of black

Yes, I thought about it. But customizing the expansion header is non-trivial and I considered it good enough. 🤷🏻‍♂️

[evnchn]

non-trivial

.props('header-class="text-gray-500"'), do consider it.

[falkoschindler]

Done: 13b4c23 ✔️

non-trivial

Once in a while NiceGUI still surprises me... 😄