Polish docs and change theme

[pradyunsg]

Toward pypa/pypa-docs-theme#8

Closes #4752 (at least)

---

List of changes:

• switch themes and enable sidebar themed like pydoc
• use build directory instead of _build
• remove .. contents:: since sidebar now has navigation
• disable smart quotes
• reduce tree depths in toctree directives
• supress a small redirection message

[pradyunsg]

I think that some pages need some restructuring now...

[pradyunsg]

Only thing remaining is figuring out what should be there in the landing index page and its sidebar.

(I've cancelled the CI jobs to save time)

[ncoghlan]

The basic approach seems reasonable to me, and I figure there can still be further iterations after folks see the impact on the live docs.

[pradyunsg]

Thanks a lot for the review @ncoghlan! ^>^

[pradyunsg]

Only thing remaining is figuring out what should be there in the landing index page and its sidebar.

More polish can be applied later. 🤷‍♂️

[ncoghlan]

@pfmoore @dstufft This change (switching to the PyPA docs theme) looks good to me, but needs review from a pip committer :)

[dstufft]

As of today Pradyun is a pip committer 😀, but I’ll take a look when I get home.

…

Sent from my iPhone

On Oct 4, 2017, at 7:52 PM, Nick Coghlan ***@***.***> wrote: @pfmoore @dstufft This change (switching to the PyPA docs theme) looks good to me, but needs review from a pip committer :) — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or mute the thread.

[pfmoore]

Happy to check, but how can I see the rendered results? (Whenever I've built the docs locally in the past I get a different theme from the website - probably me doing something wrong, but it makes it hard for me to check changes like this PR 😄)

[pradyunsg]

@pfmoore sphinx_rtd_theme package needs to be installed and used to have the RTD theme when building locally. It wasn't installed into the tox environment, causing a difference in the final theme rendered.

This is no longer the case since we use pypa_theme now. :)

[pfmoore]

Thanks

[pradyunsg]

I might have been a little bored and so, here's screenshots:

The extra whitespace in usage is fixed by #4762.

[pfmoore]

Hmm, OK. I now understand the complaint that the page isn't limited in width (and I agree with it).

I can see the value in having a unified style, but personally I'd prefer that we hold off on this till the width issue is resolved upstream (assuming we're not OK with making a local change for that on the PyPA pages).

[pradyunsg]

I'd prefer that we hold off on this till the width issue is resolved upstream

I'm cool with that. :)

[theacodes]

I staged a preview of this here: http://temp.theadora.io/pip/index.html

This LGTM, @pradyunsg requested guidance on the landing page but it's fine for now. If anything create a separate bug and @ncoghlan, @pfmoore and myself can write a short introduction to what pip is.

[pradyunsg]

@jonparrott What about this?

@pfmoore said:

I'd prefer that we hold off on this till the width issue is resolved upstream

[pradyunsg]

I staged a preview of this here

Thank you! ^>^

[pfmoore]

Having now seen a live preview, I can live with this if others are OK with it (I use a larger font, which means there's less text across the page anyway - and that fixes the problem the original screenshot had for me of too few, too long lines).

I don't know what good web design principles say about designing pages suitable for everything from portrait-format phone and tablet screens to landscape high resolution laptop and desktop screens. The ideal would be to get such guidance. But in its absence I'm going to go with "it looks tolerable to me on my commonly used devices" and not worry.

[pradyunsg]

if others are OK with it

I am okay with it. It's bearable. I'd like to see the fixed width change come through. I do mildly prefer not holding off this PR for it.

FWIW, any change in pypa_theme would propagate to us whenever it merges there; we'd just need some push to trigger the docs build, which would happen anyway.

[pradyunsg]

@pfmoore If you think this good to go, let's go ahead and make this theme switch. :)

[pfmoore]

OK let's go for it

[ncoghlan]

I confess my working theory regarding the line width issue is that the more opportunities we give it to irritate people, the more opportunities we create for it to annoy someone enough for them to decide to invest time in figuring out how to fix it :)

In the meantime, running my own browser in a non-maximised window is the main technique I use for getting text widths that I like, regardless of what individual sites do.

[pradyunsg]

Okay. http://readthedocs.org/projects/pip/

The docs build failed on ReadTheDocs. XD

@ncoghlan or @jonparrott -- is packaging.python.org served via RTD or is it on it's own build pipeline? Can we move pip's docs to the same configuration?

@pypa/pip-committers Do you guys this we should revert this or just simply wait and get it fixed?

[pradyunsg]

Ugh. That was premature. They've been failing for a while on master. Looking into it. :)

[theacodes]

Holler if you need help, I've got a bit of experience with docs builds being temperamental.

…

On Sun, Oct 8, 2017, 7:02 AM Pradyun Gedam ***@***.***> wrote: Ugh. That was premature. They've been failing for a while on master. Looking into it. :) — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#4758 (comment)>, or mute the thread <https:/notifications/unsubscribe-auth/AAPUc4kW3crJGrpQiSxAMetS4DRsjOOmks5sqNYPgaJpZM4PrSTR> .

[pradyunsg]

Oh, I forgot to mention here. Sorry!

I made #4778.

Holler if you need help

Definitely will. :)

TIL - Holler

[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.