Navigation (+other) improvements to Documentation

[pradyunsg]

Closes #4852

[pradyunsg]

I had added the Contents tree and removed it because... well, see for yourself:

[pradyunsg]

Uhm... why is everything so fragile.

#4755 "broke" this build because it sees that pip's documentation build is called with sphinx-build as the executable. None of the CI tools would detect this; it's visible as sphinx-build install in the above image.

I'm gonna put pip in place of the get_prog call because, well, it isn't supposed to return anything else here anyway.

[pfmoore]

Not sure what's wrong with the contents tree, apart from it should go after the header and the styling of the word "Contents" should match the other headings. Also, the sidebar only has one extra level - I'd strongly prefer to have full navigation from the sidebar. (But ideally not all fully expanded - does the theme support that?)

[pradyunsg]

(But ideally not all fully expanded - does the theme support that?)

Nope. Putting any more levels in fact made it look weird to me.

Not sure what's wrong with the contents tree

How it looks -- the styling. I guess, I should get over that.

apart from it should go after the header

Will do.

the styling of the word "Contents" should match the other headings.

Would need to happen in the theme.

[pradyunsg]

Deployed this branch at http://pip-pradyunsg.readthedocs.io

[pradyunsg]

I'd strongly prefer to have full navigation from the sidebar.

clarifying that when enabled, this looks weird to me -- the sidebar content wrap along multiple lines.

[pfmoore]

Looks OK to me. I would still prefer Javascript-based dynamic expansion in the sidebar, like the old theme had, but that's a problem with the new theme, and not one that I have the time to pursue, so I'm OK with accepting it as it is.

There is one check that needs fixing first, of course :-)

[pradyunsg]

Thanks @pfmoore! That should fix it.

I defer to you for clicking merge on this. :)

[pradyunsg]

If anyone has the time to pursue, I'd say they should fix it over at docs.python.org.

[lock]

This thread has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.