Add large table example

[hagenw]

This adds a large table to the table example.

I'm not sure if we really need this for documentation purposes, but it is helpful for testing how the theme can cope with it.

It can test basically two things:

1. How well can we read a table with lots of rows
2. How can we make the whole content of the table visible

For 1. the behavoir is better than expected. Usually I like when every second row is using a different color, like in the RTD tables.
But I also like the insipid approach which looks much better when using with autosummary.

For 2. the current behavior is to display a scroll bar at the end of the page, which could have the disadvantage that the user will not find it. So maybe it would be better if the scrollbar would be immediatly below the table and would only scroll the table.

[mgeier]

Suggested change

	:header: Label,Parameter1,Parameter2,Parameter3,Parameter4,Measure1,Measure2,Measure3,Measure4
	:header: Label,Parameter1,Parameter2,Parameter3,Parameter4,Measure1,Measure2,Measure3

Or did you want to add another column of data?

[hagenw]

Changed it accordingly

[mgeier]

Suggested change

	Some fancy name8,eights linear classifier,diving,noisy,emotional,0.2,0.4,4.32
	Some fancy name8,eighth linear classifier,diving,noisy,emotional,0.2,0.4,4.32

That's a strange word, but according to some online dictionaries it's spelled with "h" in the end.

[hagenw]

Changed it accordingly

[mgeier]

I agree that the scrollbar should be immediately below the table.

It looks like plain Sphinx doesn't allow that, but sphinx_rtd_theme inserts an additional <div> element to achieve this: https://github.com/readthedocs/sphinx_rtd_theme/blob/71d6d182cfeb7872c2399eac4a47d2f3c6b2c7d1/src/theme.js#L102-L103

Strangely, this manipulation seems to be done on RTD even if sphinx_rtd_theme is not used. I've just asked about this at readthedocs/readthedocs.org#8497.

I think we could insert our own CSS class in a similar way, but if possible, I would prefer a solution that doesn't need JavaScript.

BTW, there seem to be multiple table-related issues:
readthedocs/sphinx_rtd_theme#1179
readthedocs/sphinx_rtd_theme#117
readthedocs/readthedocs.org#2161

[krzychb]

How can we make the whole content of the table visible

Does the theme support changing the width of a specific page to accommodate a wider table without the scrollbar?

[hagenw]

I guess at the moment not. There is a way to do this, I implemented a solution where you have to provide the page names you want to have as wide pages to a config option, see https://audeering.github.io/sphinx-audeering-theme/example-wide-pages.html

But it's not the most elegant solution.

[mgeier]

Does the theme support changing the width of a specific page to accommodate a wider table without the scrollbar?

No, not explicitly.

And I'm not sure if it's a good idea to add such an option, because if we do that, we might as well provide every option for specific pages, which will quickly become confusing.

Also, I'm not even sure if making the page wider is actually a good solution.
I think it would be better to allow the table to protrude over the left and right border of the parent element, but I don't know if that's even possible with CSS.
Regardless, none of this helps visitors with narrow screens, they would need a scrollbar anyway.

Regarding work-arounds: to make a single page wider, you don't really need the support of the theme, you can just include something like this in the reST code of the page:

.. raw:: html

    <style>
    div.body {
        max-width: 1600px;
    }
    </style>

[krzychb]

@hagenw and @mgeier thank you for detailed answers, tips, and comments. I got a lot of inspiration checking https://insipid-sphinx-theme.readthedocs.io/en/0.2.8/ and your repositories.

[mgeier]

I've just created #66 which implements wrapping tables into <div> elements (as mentioned above: #61 (comment)) to make them scrollable.

I've also applied the same thing to images, because I think they should behave the same way.

[mgeier]

Doing this to images doesn't seem to work (see #66), therefore I'm suggesting an alternative: #68.