This mostly looks good to me, but there are a couple of layout quirks it highlighted:

1. The user-visible "Page Status" entries make the opening paragraph placement jump around a bit, since we don't have that on every page. Perhaps we should just drop that line for any page where the status is "Complete as of the last reviewed date", and only keep it for the known-incomplete pages?

2. With the new truncated sidebar navigation and narrower reading viewport, the "Packaging and Distributing Projects" section header should probably be shortened to just "Distributing Projects" (although I think the reason we had the current longer title was to ensure that "Packaging" appeared in at least one of the top level nav links)

I also think we're going to have to make some changes to the way the side bar navigation works, as the single top level listing isn't particularly helpful, especially once you start digging down into the Additional Topics section.

Looking at http://flask.pocoo.org/docs/0.12/foreword/ for inspiration, I'm wondering how hard it would be to add (below the top level navigation links) sidebar sections for:

• Page Contents (table of contents for the current page)
• Local Navigation (the up/next/previous links that Flask has under "Related Topics")

The user-visible "Page Status" entries make the opening paragraph placement jump around a bit, since we don't have that on every page. Perhaps we should just drop that line for any page where the status is "Complete as of the last reviewed date", and only keep it for the known-incomplete pages?

I'm good with this.

With the new truncated sidebar navigation and narrower reading viewport, the "Packaging and Distributing Projects" section header should probably be shortened to just "Distributing Projects" (although I think the reason we had the current longer title was to ensure that "Packaging" appeared in at least one of the top level nav links)

I can change this title here, though personally I'd like the title to be shortened to "packaging projects".

I'm wondering how hard it would be to add (below the top level navigation links) sidebar sections for

Not hard, but I've been wanting to better organize the files here. If I do those together in a separate PR, it'll be significantly easier.

I promise I'm coming back to this, I've just been sick.

@ncoghlan I've updated this to remove the markers. I'm gonna hold off on changing the name until I do the next PR to organize the docset into subfolders.

The staging site is updated: http://temp.theadora.io/pypug/distributing.html

Is there anything else I need to do before merging this?

We don't have great communication channels for pre-announcing upcoming visual changes like this, but it's probably worth giving at least a day or two's notice to distutils-sig and a pointer to the discussion in #304 before actually landing the change.

I'm not volunteering to do it, so it would be fine to skip this step, but I'm wondering if it may be worth starting to use the PSF blog to pre-announce some of the upcoming changes. See http://pyfound.blogspot.com.au/2017/01/time-to-upgrade-your-python-tls-v12.html for a previous example of that related to a PyPI change.

Restructuring and a theme change for the packaging user guide doesn't have the same risk of breaking anything that that did, but it still has significant potential to surprise users when they're expecting the site to look a particular way, and it suddenly starts looking different.

Syncing up with the Py3 docs is my own preference (see #62 for more background on that), especially if that can be applied across all the PyPA projects as discussed in #304.

@ncoghlan this has been updated to use pydoctheme. I personally like the way it turned out.

New staging here: http://temp.theadora.io/pypug-pydoctheme/index.html
Compared to alabaster here: http://temp.theadora.io/pypug/index.html

I'll send off an email to distutils-sig tomorrow to get some discussion going. :)

Alright, cool. This is finally ready for review, but please do not merge.

1. This is "staged" here: http://temp.theadora.io/pypug-pydoctheme
2. pypa-theme is a package that lives in this repository for the moment (so I can demonstrate it), but if distutils-sig wants to move forward with standardization, it will move to github.com/pypa/pypa-theme.
3. I have kept the link to the PSF donate page in the footer.
4. I have made small changes from the upstream pydoctheme as they made sense. Notably, I removed the page-specific templates and javascript (as we don't have those pages).

I added the [WIP] prefix to indicate the "Do not merge" status.

General idea and approach still sounds good to me :)

I wonder if you should check with python-dev. If I recall discussions about the new theme correctly, one of the goals was to have a distinctive theme for CPython.

@merwok good point, I couldn't find any recent discussions. @ncoghlan is a core developer and was one of the (many) people asking to align with pydoctheme, so I'm mostly going off his guidance. Nick, do you know if we would run awry of the core team / PSF if we use the theme? (I know we already have branding permission)

Note that the PyPA/CPython overlap is more than just me - it includes @dstufft and @pfmoore as well :)

I think PEP 453's bundling of pip (and the policies around that: https://www.python.org/dev/peps/pep-0453/#policies-governance), together with the use of a python.org subdomain for the packaging user guide itself, and the organisational backing of the PSF's Packaging Working Group, mean it's reasonable to re-use the theme to better reflect that collaborative governance.

It's probably worth asking on python-dev about preferred names for the theme package, though - it may make more sense to call it "psf-docs-theme" and suggest that folks avoid using it if their project governance structure doesn't run directly through the PSF.

python-dev thread regarding pypa-theme vs psf-docs-theme vs both: https://mail.python.org/pipermail/python-dev/2017-May/148029.html

Looking up something on the Python docs on my phone this morning alerted me to a somewhat serious step back compared to the RtD theme: it's much more difficult to navigate the docs on mobile, compared to the RtD theme's menu drawer. All of the sidebar, header, and footer text is awfully small—I had a hard time with it. Some screenshots, to compare:

I'm not sure that it's a showstopper necessarily (I don't know what, if any, work is being done on making the theme more small-screen friendly), but it seemed like something I ought to call attention to.

I don't think the current pydocs theme has had any work done on it to make it responsive at all, so if there are some CSS changes that could be taken from the Alabaster or RtD themes to improve mobile readability, that could potentially be useful for the CPython docs as well.

don't think the current pydocs theme has had any work done on it to make it responsive at all

Yep, this is true. I'm not sure how much weight we want to put on this - I'm not sure what kind of person reads Python packaging documentation on their phone :D

That said, if we do go the route of python/pydoctheme -> pypa/pypa-theme, it's possible some one could add responsiveness upstream and we can benefit from that easily. :)

I merged python/python-docs-theme#1, so the common theme should now be pip-installable via:

git+https://github.com/python/python-docs-theme.git#egg=python-docs-theme

@ncoghlan PR updated to use that. I still think it's a good idea for use to create pypa/pypa-docs-theme. Up to you and @dstufft.

@jonparrott No opposition from me, it just means it needs to be copied in as a file, rather than selected from the dropdown that GitHub provide during repo creation :)

@ncoghlan Hahaha, laziness wins every time.

I should (hopefully) have some time tomorrow afternoon to populate that repo and get this PR updated and ready to merge. :)

Once pypa/pypa-docs-theme#1 is merged, I'll be able to update this to use our common theme and then it'll be ready to merge. :)

Alright, this is ready for final review & merge. @ncoghlan @dstufft

Staging is here: http://temp.theadora.io/pypug-pydoctheme/index.html

I'll do a quick post to distutils-sig about it.

Thanks!

Merging, but if @dstufft has any post-hoc comments I'll address them in a follow-up PR. :)

Hi! Just wanted to point out some things I spotted. These are probably just nits.

On http://temp.theadora.io/pypug-pydoctheme/tutorials/index.html, the part that shows that adds contrast to the "«" for collapsing the sidebar does not extend till that character, making it barely visible unless you look for it.

Also, the same "«" isn't staying in the (vertical) center as I scroll down, it doesn't move. I think it does on the CPython docs currently.

Where do I make issues for these - on the python org or the pypa org?

@pradyunsg huh, good catch. I'll track that down now, I think there was just some wires crossed with the new collapsable sidebar.

@jonparrott Thanks! ^.^

If there's anything else, I'll make issues on the PyPA theme?

Yep, please do! Thank you.