Improvements for autosummary tables

[Yura52]

Hi! Thank you for the great theme!

When testing it for my project (namely, for this page), I noticed that in the case when there are several autosummary tables on one page, the result could look better if:

• the column width of all tables was the same
• there were no vertical lines at all

I am not completely sure about the second point, but is inspired by the fact that in academic publications it is often recommended to make tables without vertical lines. And I tend to agree that without them, tables indeed look better in most cases.

The source code of the page:

.. _delu:

delu
====

.. currentmodule:: delu

.. automodule:: delu

.. rubric:: Data and Tensors

.. autosummary::
   :nosignatures:
   :toctree: api
   :template: class.rst

   Stream

.. autosummary::
   :nosignatures:
   :toctree: api

   collate
   concat
   iter_batches

.. rubric:: Utilities

.. autosummary::
   :nosignatures:
   :toctree: api
   :template: class.rst

   ProgressTracker
   Timer

.. autosummary::
   :nosignatures:
   :toctree: api
   :template: class_just_autoclass.rst

   evaluation

.. autosummary::
   :nosignatures:
   :toctree: api

   improve_reproducibility

.. rubric:: Submodules

See the sidebar on the left.

How the tables look with Sphinx-Material:

With Furo:

If you want to try it yourself, set up the development environment and run make docs.

Another example for which I do not have a Furo-based counterpart is https://pytorch.org/docs/stable/nn.html

[Yura52]

Hi @pradyunsg ! What do you think about this suggestion?

[pradyunsg]

Oh hai, I completely missed this. Thanks for the mention. :)

[pradyunsg]

So... IIUC, there's three suggestions here:

1. Force 100% width on tables.
2. Remove vertical separators for tables.
3. Have uniform/50% width on tables.

Let's restrict the scope of all of these to auto-summary tables.

1. That seems reasonable.

2. I'm lukewarm on this, to be honest. https://pradyunsg.me/furo/reference/tables/ has examples where removing horizontal separators would remove user-visible information about how the table is structured. On the other hand, these tables won't have complex structures -- we know exactly what they'll look like.

3. Sphinx-material is actually overriding the behaviour encoded by Sphinx in the table's markup:

   https://github.com/sphinx-doc/sphinx/blob/v4.2.0/sphinx/ext/autosummary/__init__.py#L417-L425

   https://github.com/bashtage/sphinx-material/blame/6e0ef822e58df57d6a9de5a58dc40c17fc34f557/sphinx_material/sphinx_material/static/stylesheets/application-fixes.css#L47

   The table markup has colgroup for setting the widths, something that Furo is respecting and sphinx-material is not. Those originate from the underlying autosummary plugin. I'm torn on this, because I think the right fix is for Sphinx to use more reasonable numbers, like 30-70 or even 50-50, and... as is the thing that I am finding myself saying a lot lately... I'd prefer that we fix this problem where it originates from instead of papering over it in a piece of code that I maintain.

For now, my pragmatic suggestion would be: You can add your own CSS file that contains the following, for now. I'll come around to experimenting with this over the weekend, hopefully.

.longtable {
    width: 100%;
}

.longtable tr td:first-child {
    width: 50%;
    white-space: nowrap;
}

This should get you basically the behaviours that you want, minus the vertical line removal -- but that... as I said, I'm lukewarm on. I think removing that should be straightforward, but I don't wanna open a 5th editor window to look that up. :P

[Yura52]

Thank you for the reply! And wow, this css snippet works like a charm! Though 50% was a bit too much in my case, made it 35% for now :)

One more thing that I did not mention in the first message is how sphinx-material "merges" autosummary tables. Is it possible to achieve this with some more css magic so that the following two tables would look like one table with two rows? I cannot merge them in one autosummary statement because they use different :template: values.

Regarding the vertical lines, I indeed observe that, in papers, tables without vertical lines usually look better and more lightweight in a good way. So I would explore this option specifically for autosummary tables, but this is not critical I guess :)

[pradyunsg]

.table-wrapper {
    margin-top: 0;
    margin-bottom: 0;
    paading-top: 0;
    paading-bottom: 0;
}

Although, I don't know if that will affect anything else negatively?

[Yura52]

I've tried this and it works perfectly for the specific purpose of merging autosummary tables, but then other elements right before and after the tables become a bit too close to the tables sometimes, so it is not obvious to me if it should be the default. Ideally, the padding should be removed only between two autosummary tables, but I don't know if that is possible.