Documentation: Improve homepage

[binste]

The current homepage looks empty on larger screens:

In this PR, I increased the size of the gallery (inspired by the VL docs and added cards with short descriptions about the main sections in the documentation (inspired by the pandas docs. You can see the result here or in the screenshots below:

Large screen (27inch 2560x1440):

Laptop (13inch 2560x1664):

Mobile (iPhone SE emulation):

[mattijn]

Really nice improvement @binste! Love it. Included one inline suggestion.

[joelostblom]

I can have a look at this tonight.

[mattijn]

@binste, I see some commits regarding API, but if I click on the API tile at the prototype page at your repo I get a 404 error. Is that intended?

[binste]

Figured out what's the issue, fixed it and redeployed the prototype page.

In this PR, I had to rename the API.rst file to api.rst as else somehow I got an error that the API reference does not exist. For this, I had to use git mv so that git recognizes the renaming to all lowercase, else it thinks it's still the same file. However, I forgot to do the same in the altair-docs repo for the html file so there it was still called API.html (renamed the html file in this commit).

-> When you deploy the next version of the docs with this PR, after deploying the docs as usual you will need to run git mv user_guide/API.html user_guide/api.html in the docs repo and commit and push the change. Afterwards, it should work.

[joelostblom]

I have a quick look at this and I think it looks great overall! Love the cards! A few minor comments (the first being the most important I think):

• I like that the text column on the VegaLite page is narrower than the gallery image:
  

  On the Altair site the text and the cards looks a bit too stretched out horizontally in my opinion (and maybe also slightly too large font for the sentence just under the gallery image? But that might just be my personal taste). Aligning the title with the more narrow text column would also look nice I think (like on the VegaLite page).
  

• Personally I don't know if the API reference is exciting enough to be promoted on the front page, but I also can't think of something better to replace it with... maybe only three cards? But I like the layout with four cards, this is probably fine as it is right now.

Thanks for improving this part of the docs!

[binste]

Thank you for the feedback! I'd also prefer to have the gallery stretched across the whole page and then again the text a bi narrower but I didn't manage to make that happen within the Sphinx theme. There are some infos here on the layout of the theme. From that and inspecting the source code, I think we'd need to either find a way to make the gallery stretch to more then the width of it's parent containers or do bigger changes to the layout templates. I tried the approaches suggested at https://stackoverflow.com/questions/5581034/is-there-a-way-to-make-a-child-divs-width-wider-than-the-parent-div-using-css but they only made the gallery wider by a bit but not as in the VL docs.

This is why I made the page slightly wider then in the VL docs as a compromise so that the gallery is wide but the page is also not too wide as then the text and cards would be stretched even more.
Any ideas how we can stretch the gallery?

Regarding the API reference, I actually find it one of the most useful parts as I use it a lot to look up the meaning of some parameters but not sure if that fully comes through and is the same for most users. Let's replace it once we have something more exciting as you mentioned.

(Removed some unused css in the last commit, no visible change)

[joelostblom]

I'd also prefer to have the gallery stretched across the whole page and then again the text a bi narrower but I didn't manage to make that happen within the Sphinx theme.

I don't necessarily think the gallery need to stretch to the end of the page, it is more the ratio between the gallery width and the text width that I think could be increased. Is it possible to try the other way around and make the text column on the first page more narrow? Maybe we could use the width of the title as the guideline and make sure the text and card fit within that width and then center the title, cards, and text in a column that is more narrow than the current gallery?

[mattijn]

Great example how the docs are used differently at study and at work:

Personally I don't know if the API reference is exciting enough to be promoted on the front page

vs

Regarding the API reference, I actually find it one of the most useful parts as I use it a lot to look up the meaning of some parameters

I like it that we realize this and that we can serve both.

[binste]

Fully agree! It's great to have people with different backgrounds weigh in on these topics :)

I think I figured out how to stretch the gallery and make the text narrower again. Will push an update soon.

[binste]

The gallery shadow now stretches all the way to the edges, same as in VL docs, and the examples have the same width as the header. The title and text are again a bit narrower (same width as VL docs). I replaced and reordered some examples as well. Preview docs are updated. I think this looks great, quite happy with the outcome but let me know if you see any additional improvement potential. :)

[joelostblom]

This is looking really neat! Great working figuring out how to get the gallery to stretch 🙌 ! Merging.