feature: prevent overflow for long object names/headings

joaopalmeiro commented 3 months ago

Hi! 👋

Is your feature request related to a problem? Please describe.

If functions or classes (or other objects) have very long names, their names will overflow and negatively influence their readability as well as that of the table of contents:

I apologize for sharing a dummy example, but I can't show the real examples where I implemented custom CSS to avoid it.

This issue is somewhat related to an old issue about the table of contents. It seemed to me that the best option would be to open the issue in this repository because the solution proposed below can, therefore, be applied to elements generated by mkdocstrings + mkdocstrings-python and be independent of the selected theme.

Describe the solution you'd like

Style elements classed with doc-object-name as follows to prevent overflow:

/* Prevent overflow of long object names. */
.doc-object-name {
  word-break: break-all;
}

This change could be implemented in the style.css files of the material and readthedocs templates.

Describe alternatives you've considered

The change proposed above can also be applied to other CSS classes, such as doc-heading or doc-KIND-name.
Instead of break-all, the word-break property could be set to break-word.
Instead of wrapping the object names, the part of the name to overflow could be hidden and add ellipsis to signal this behavior to users.

Additional context

mkdocs: 1.6.0
mkdocstrings[python]: 0.25.2
mkdocs-material: 9.5.31

Boost priority

Boost priority in our backlog through Polar.sh. Higher pledge, higher priority.
Minimum pledge by user/organization is $5, minimum amount for boost is $30.
View all issues with pledges.
We receive the funds once the issue is completed and confirmed by you.
Features with the insiders label are released to sponsors first, and tied to a funding goal.

pawamoy commented 3 months ago

Hi @joaopalmeiro, thanks a lot for the detailed report, and the included suggestions for a solution!

I was exactly going to suggest using CSS to fix this. I suppose we could include such rules in the default CSS provided by mkdocstrings handlers. I'll try the different rules suggested and see if one seems to fit best.

joaopalmeiro commented 3 months ago

Nice! 👌

Let me know if you want me to open a PR with the best proposal later or if you need some other kind of help.

mkdocstrings / python