Autosummary tables have strange line wrapping

[mhostetter]

I found that sometimes autosummary tables have very strange line wrapping. Below the functions are wrapped across three lines, even though the second column (function summary) hasn't yet reached the end of the table.

I'm willing to help resolve the issue (to the best of my ability). Can @jbms and/or @2bndy5 point me in the right direction? Is this an HTML decision of when to wrap text in each column?

Source file:

.. rubric:: Polynomial tests
.. autosummary::
   :toctree:

   is_monic
   is_irreducible
   is_primitive
   is_square_free

sphinx-immaterial (https://galois.readthedocs.io/en/latest/api/polys.html):

sphinx_rtd_theme (https://galois.readthedocs.io/en/v0.0.24/api/polys.html):

[2bndy5]

I noted this back when this theme was just a PR to sphinx-material theme. @jbms actually went through and customized the autosummary behavior for his site, so it may require additional files (or src code snippets) from tendorstore docs' src. Beware, the customization may not be aligned with what you'd expect from vanilla autosummary (its somewhat opinionated).

[jbms]

We should be able to fix this issue pretty easily with some css rules for the table.

The TensorStore autosummary is completely independent of the built-in sphinx autosummary module and does not use tables at all.

[2bndy5]

Looking at the generated html from @mhostetter linked sample, the autosummary table includes a <colgroup> element that influences the width of the cells for each column. Observe:

<table class="longtable docutils data align-default">
  <colgroup>
    <col style="width: 10%">
    <col style="width: 90%">
  </colgroup>
  <tbody>
    <!-- table rows -->
  </tbody>
</table>

I'm able to remedy this using a new CSS rule:

.longtable.docutils.data.align-default colgroup col {
  width: auto !important;
}

The !important is required to override the inline CSS from HTML. There's also an issue that still remains: word-wrapping long function signatures.

Although this rule will solve the word-wrapping problem:

.reference.internal .xref.py.py-obj.docutils.literal.notranslate {
  word-break: normal;
}

[mhostetter]

Thank you, @2bndy5. I just added that to my extra CSS file and get much better line wrapping!

As you mentioned, there are a couple cases with long function names that wrap a little strangely. But still much better than before!

[2bndy5]

I updated my comment to compensate for the long function signatures

[mhostetter]

And after testing with...

.reference.internal .xref.py.py-obj.docutils.literal.notranslate {
  word-break: normal;
}

I get...

Adding these two CSS snippets solve this problem for me. Might be worth adding a note of this in the documentation? Otherwise, I'm willing to close this issue.

.longtable.docutils.data.align-default colgroup col {
  width: auto !important;
}

.reference.internal .xref.py.py-obj.docutils.literal.notranslate {
  word-break: normal;
}

[2bndy5]

@jbms what do you think? Should it be in the theme CSS? Or should we pin the issue and tell autosummary users (via docs) to add the extra CSS rules?

[jbms]

If you believe this to improve autosummary without any downsides, then it seems it may as well be fixed in the theme itself.

I wonder why a width of 10% is being specified. This theme differs from most other themes in that it does not include any of the default basic theme CSS --- perhaps the basic theme CSS includes something that fixes the autosummary tables for other themes.

[2bndy5]

perhaps the basic theme CSS includes something that fixes the autosummary tables for other themes.

Good lead. I'll have to look into that.

I think the easiest way to ensure no undesired effect is search through the theme CSS and check that there aren't any CSS classes also used by autoaummary. I made the rules as specific as possible...

[2bndy5]

I couldn't find anything in the basic theme CSS that was related to the combination of CSS classes that autosummary uses. I also looked in RTD theme's CSS and found nothing specific to the word-break or width properties related to the CSS classes used by autosummary.

This led me to think that there's a rule that mkdocs-material is using that breaks expected behavior with autosummary. Then I found it:

sphinx-immaterial/src/assets/stylesheets/main/_typeset.scss

Lines 195 to 199 in 6ceccff

	// Inline code block
	code {
	padding: 0 px2em(4px, 13.6px);
	font-size: px2em(13.6px);
	word-break: break-word;

It seems that mkdocs-material would allow words to be broken up for inline code literal elements.

Without using the above CSS rules I suggested earlier, I overrode the mkdocs CSS rule like so:

.reference.internal .xref.py.py-obj.docutils.literal.notranslate {
  word-break: normal;
}

and that fixes all the autosummary tables. I don't see any problem with other code blocks (yet - I'm still testing), but I think this solution just got a bit easier to solve. There doesn't seem to be a need to adjust the width at all.

[2bndy5]

I don't see how this rule would interfere with other CSS rules because the only rules that use a reference class exist in _api.scss, and those are scoped to children of a dl.api-field selector.

@jbms I'll submit a PR that adds this rule override in _api.scss - mostly because _api.scss doesn't exist in upstream CSS and autosummary is related to documenting python API anyway.

[2bndy5]

@mhostetter You can revert you solution for mhostetter/galois#266 and pin your docs to sphinx-immaterial>=0.3.1. Using the latest release will also uniform your autosummary tables' widths (my initial CSS solution was overzealous).

[mhostetter]

Great! Thank you, @2bndy5!