Title line overflows in documentation

[aryankeluskar]

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:

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;

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;

[2bndy5]

We actually implemented a more API-friendly solution for ToC entries using <wbr> injection.

sphinx-immaterial/sphinx_immaterial/nav_adapt.py

Lines 184 to 192 in 3951651

	def _insert_wbr(text: str) -> str:
	"""Inserts <wbr> tags after likely split points for API symbols."""
	# Split after punctuation
	text = re.sub("([.:_-]+)", r"\1<wbr>", text)
	# Split before brackets
	text = re.sub(r"([(\[{])", r"<wbr>\1", text)
	# Split between camel-case words
	text = re.sub(r"([a-z])([A-Z])", r"\1<wbr>\2", text)
	return text

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

[2bndy5]

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

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

results in

[jbms]

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.