Tables in docs make looking up functions unnecessarily hard

[typesanitizer]

Before anything else: I think xarray is awesome and I love using it! It has made my life so much simpler over juggling dictionaries of arrays and maintaining indices in my head. Thank you to all contributors 😄!

Problem description

I can't read the method tables all at once (i.e. method name + args + short description). This makes it unnecessarily hard to see which function is doing what. Here are some pictures using Firefox, with and without tree-style tabs, and on a larger monitor for the last one.

You have to scroll horizontally to read. This makes using a mouse terrible as the horizontal scrollbar is at the bottom of the table and not the bottom of the screen (the table is too big vertically to fit on the screen). The "hack" I'm using is to start selecting some text inside the table and drag the cursor to the edge leading to horizontal scrolling.

Suggestion

It would be nice if you didn't have tables but just inlined the short description like this one.

This allows text to wrap properly to the next line if needed. The only shortcoming is that the page takes up more vertical space but that's not such a big deal imo.

I'm happy to contribute a patch if someone can point me in the right direction. Is this a problem with sphinx_rtd_theme? I don't recall having similar issues with other packages' docs hosted on readthedocs.

[shoyer]

This is indeed the default behavior for sphinx_rtd_theme. I'm certainly open to better alternatives!

I would be slightly reluctant to adopt the two line version you show for DataArray.to_series() because it takes up significantly more vertical space, which makes the docs harder to skim.

The API docs for pandas (http://pandas.pydata.org/pandas-docs/stable/api.html) show a nice alternative: the description in the right column is allowed to span multiple lines if necessary (rather than relying on horizontal scrolling).

Apparently this is a common complaint -- I just Googled and turned up a how-to guide for fixing it.

I would encourage you to put together a PR. Try using our environment.yml file to setup a conda environment.

[stale]

In order to maintain a list of currently relevant issues, we mark issues as stale after a period of inactivity

If this issue remains relevant, please comment here or remove the stale label; otherwise it will be marked as closed automatically

[dcherian]

now fixed.