search

jbms / sphinx-immaterial

Adaptation of the popular mkdocs-material material design theme to the sphinx documentation system
https://jbms.github.io/sphinx-immaterial/
Other
177 stars 28 forks source link

Title line overflows in documentation #365

Open aryankeluskar opened 1 week ago

aryankeluskar commented 1 week ago

Describe the bug

While browsing the documentation for statsmodels, certain functions have really long names that overflow. The problem is the text doesn't wrap, causing some of the text to not be selectable or even visible (as showing in the image). Eg: https://www.statsmodels.org/stable/generated/statsmodels.regression.mixed_linear_model.MixedLM.html

Original:

image

Potential Fix 1:

I believe this could be a simple fix by enabling overflow to scroll. A potential solution could be adding the following to the documentation's CSS: 

overflow: scroll;
image

Potential Fix 2:

I believe this could also be a simple fix by enabling overflow-wrap to anywhere or break-word. A potential solution could be adding the following to the documentation's CSS: 

overflow-wrap: anywhere;
image
2bndy5 commented 1 week ago

We actually implemented a more API-friendly solution for ToC entries using <wbr> injection. https://github.com/jbms/sphinx-immaterial/blob/39516511cfa74c70f122c753eeb6a384048fd9c0/sphinx_immaterial/nav_adapt.py#L184-L192 image image

However, we don't alter the doc/section titles in the same way.

2bndy5 commented 1 week ago

FYI, our CSS also has a rule that appends a ellipsis if overflow occurs. Adding this class to the raw html

<h1 id="long-api-name" class="md-ellipsis">long.API.name</h1>
CSS class definition

```css .md-ellipsis { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; } ```

results in image

jbms commented 3 days ago

A solution based on _insert_wbr for the titles seems like the best option. Ellipses are unfortunate because for API documentation it really is important to see the full string, especially the end of it.