mkdocstrings / python

A Python handler for mkdocstrings.
https://mkdocstrings.github.io/python
ISC License
190 stars 35 forks source link

feature: prevent overflow for long object names/headings #177

Open joaopalmeiro opened 3 months ago

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:

Screenshot 2024-08-05 at 12 27 28 Screenshot 2024-08-05 at 12 28 37 Screenshot 2024-08-05 at 12 29 39

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

Additional context

Boost priority

Fund with Polar

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.