DOC: replace long table of contents on home page with main links

[jorisvandenbossche]

This is a proposal to remove the long table of contents on the documentation home page and replace it with a highlight of the main parts of the documentation.

Reasons: I don't think the long table of contents resulted in a very attractive landing page of the docs. And further, it was also a "manual" table of contents which would therefore easily get out of date. And with the new content, we can also at the same time give some explanation on the organization of the docs.

So would like to get feedback on the general idea. The wording in the different boxes can certainly still be improved. And we could also make similar boxes to point to eg the installation guide or for the different "getting help" links.

It's using some bootstrap elements ("cards") that can be used now since the sphinx theme is based on bootstrap (and all credit to @stijnvanhoey for the html/css part, I re-used some content of what he worked on for the getting started guides, a PR for that is coming shortly). Screenshot of how it currently looks below, and a live version can be checked here: http://jorisvandenbossche.github.io/example-pandas-docs/html-doc-home/

[jreback]

+1 on this.

[stijnvanhoey]

@jorisvandenbossche proposal for the icons of the four items:

[WillAyd]

lgtm - I think this is a great idea

[TomAugspurger]

A few suggestions on the card text.

[jorisvandenbossche]

cc @datapythonista

@TomAugspurger thanks for the textual suggestions!

[datapythonista]

Seems like an improvement, but the home of the docs is not linked from the website. And aftet the discussion we had on the PR to address that, its still unclear to me what vision we've got about the website.

Feel free to merge, but personally I can't have an opinion on this without knowing what's the expected navigation. This feels right to me if we expect users to land in the home of the docs, and have the website as an addendum of the docs. If we have the website home as the home, and we expect people to navigate from there with the current navigation, I don't think this page will have visits, more than people in the docs looking for another section. Then it may be worth keeping all the subsections linked, and not add los of steps to go from one é page to another.

[jorisvandenbossche]

@datapythonista there are still plenty of ways to end up on the home page of the docs (eg googling "pandas docs", from links all over the internet, from clicking to the home page from somewhere else in the docs, ...), so personally, I think a more useful and better looking home page is an improvement anyway.

[jorisvandenbossche]

Given the mostly positive comments here, going to merge this in a bit.
I am going to tag it as 1.0.0, it's no crucial fix, but since it's otherwise still going to be the old home page for a few months on the stable docs, nice to backport it I think (and it's not risky to backport)

[TomAugspurger]

+1 to merging.

I don't suppose you've had a chance to check the PDF build with this 😄? I'm having trouble thinking through whether or not it'll be completely broken with these changes.

[jorisvandenbossche]

Ah, good point ;) Let me try if .. only:: html would help with that

[jorisvandenbossche]

I suppose that since we are currently using ..raw:: html that this will not be included in the latex output.

[TomAugspurger]

Right, to clarify I was mostly concerned about the toctree getting broken. But IIUC, this is not changing the actual sphinx toctree?

[TomAugspurger]

Let's merge this and see how things look.

I'll try out a PDF build once it's in.

[lumberbot-app]

Owee, I'm MrMeeseeks, Look at me.

There seem to be a conflict, please backport manually. Here are approximate instructions:

1. Checkout backport branch and update it.

$ git checkout 1.0.x
$ git pull

2. Cherry pick the first parent branch of the this PR on top of the older branch:

$ git cherry-pick -m1 74a5edc3c5af8a22a44b03eabaa5cdadda0cd8fd

3. You will likely have some merge/cherry-pick conflict here, fix them and commit:

$ git commit -am 'Backport PR #31148: DOC: replace long table of contents on home page with main links'

4. Push to a named branch :

git push YOURFORK 1.0.x:auto-backport-of-pr-31148-on-1.0.x

5. Create a PR against branch 1.0.x, I would have named this PR:

"Backport PR #31148 on branch 1.0.x"

And apply the correct labels and milestones.

Congratulation you did some good work ! Hopefully your backport PR will be tested by the continuous integration and merged soon!

If these instruction are inaccurate, feel free to suggest an improvement.

[jorisvandenbossche]

I was just checking, seems to be all fine

[jorisvandenbossche]

Will do the backport