Requests from review of #1776 (merging docs into main).

[jpivarski]

Which documentation?

Tutorials site

What needs to be documented?

This is a follow-up of #1776 (review), which is an approval of merging the docs branch into main as-is, but with some to-do items to be picked up later. This issue copies those into a bulleted list.

• Vertical margin around the badges/buttons on the front page so that they are still distinct when the window is narrow or someone is looking at it on their phone.
• Helpful messages on the "Try it in your browser" page (see below).
• Better sizing of Retrolite on small screens
• All of the sections containing ak.* functions (everything defined in src/awkward/operations/) should be contiguous, before the section on "Low-level layouts". This is so that someone searching for an operation they can't quite remember the name of is less likely to miss it. The "Converting between backends", "Indexing and grouping", and "Copying and packing arrays" belong to this category.
• Remove the "Additional documentation" section (which is unnecessary and out of date, including the diagram).
• The kernel specification should be generated and included.
• The AwkwardForth sub-sections may be suppressed on reference/index.html and the kernel specification sub-sections have to be suppressed. They would flood that page.

That's it!

[agoose77]

Yes, I'd like to improve the buttons. Ideally, I'd prefer to use something like the sphinx-design buttons, but they don't support the dynamicism that the shields.io badges do. We can just add a CSS margin to the icon class.

[agoose77]

The kernel specification is being generated, at least locally. I'm not sure why it's not appearing in the built docs

Ah, it's the change I made to use runpy. I'll fix this in the PR that closes this issue.

[agoose77]

@jpivarski could you clarify where you think RetroLite could be better on smaller screens? :)

[jpivarski]

Whatever I had been thinking, nevermind: I just tried out https://awkward-array.readthedocs.io/en/main/getting-started/try-awkward-array.html in a window with varying sizes and it scales well: it drops the right bar and then the left bar as the window gets narrow, and the width of the RetroLite widget uses all the available space in its column, which is good. Considering that there's nothing interesting in the right bar, it would be nice if that was always collapsed for this page, but I doubt you can make layout decisions like that on a per-page basis.

I also checked it on a simulated phone: http://mobiletest.me/iphone_5_emulator/?u=https://awkward-array.readthedocs.io/en/main/getting-started/try-awkward-array.html And it's fine there, too. As much as can be expected.

Another nice-to-have: on all platforms, there are two scroll bars for the page and for RetroLite, respectively. The RetroLite widget scales width with the page. It would be awesome if it also scaled height with the page so that the outer page never has a scroll bar and we see only one scroll bar. I'd be surprised if RetroLite has that option, though.

I also tried it on my physical phone, and yeah, the two scroll bars is a bit of a problem: one needs to be high enough to see the ▸ button, which is necessary because there's no "shift-enter." Phones have different sizes, so you can't even set the vertical size to ensure that the header is always visible. Rocks and hard places.

Bottom line, though: there's no action item here. The visibility of RetroLite is as good as is probably possible.

[agoose77]

Thanks Jim! I think I've tackled the scaling issue; unfortunately Sphinx is oriented around content-driven layouts rather than layout-driven, so we have to hack the DOM styles a little to make everything scale properly. Here's an example in #1832