New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Switch to pypa theme #305

Merged
merged 12 commits into from Jun 15, 2017

Conversation

Projects
None yet
5 participants
@theacodes
Member

theacodes commented Apr 24, 2017

Towards #304

@theacodes theacodes requested review from dstufft and ncoghlan Apr 24, 2017

@ncoghlan

This comment has been minimized.

Member

ncoghlan commented Apr 25, 2017

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")
@theacodes

This comment has been minimized.

Member

theacodes commented Apr 25, 2017

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.

@theacodes

This comment has been minimized.

Member

theacodes commented May 2, 2017

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

@theacodes theacodes force-pushed the theacodes:alabaster branch from 5049d7f to d45ecc6 May 22, 2017

@theacodes

This comment has been minimized.

Member

theacodes commented May 22, 2017

@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?

@ncoghlan

This comment has been minimized.

Member

ncoghlan commented May 23, 2017

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.

@theacodes

This comment has been minimized.

Member

theacodes commented May 23, 2017

@ncoghlan

This comment has been minimized.

Member

ncoghlan commented May 23, 2017

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.

@theacodes

This comment has been minimized.

Member

theacodes commented May 23, 2017

@ncoghlan

This comment has been minimized.

Member

ncoghlan commented May 23, 2017

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.

@theacodes theacodes changed the title from Switch to alabaster theme to Switch to pydoctheme May 23, 2017

@theacodes

This comment has been minimized.

Member

theacodes commented May 23, 2017

@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. :)

@theacodes theacodes force-pushed the theacodes:alabaster branch from 962f4aa to 5f677bd May 26, 2017

@theacodes

This comment has been minimized.

Member

theacodes commented May 26, 2017

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

@ncoghlan ncoghlan changed the title from Switch to pydoctheme to [WIP] Switch to pydoctheme May 26, 2017

@ncoghlan

This comment has been minimized.

Member

ncoghlan commented May 26, 2017

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

General idea and approach still sounds good to me :)

@theacodes

This comment has been minimized.

Member

theacodes commented May 26, 2017

@merwok

This comment has been minimized.

merwok commented May 26, 2017

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.

@theacodes

This comment has been minimized.

Member

theacodes commented May 26, 2017

@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)

@theacodes theacodes referenced this pull request May 26, 2017

Closed

Master documentation plan #317

6 of 6 tasks complete
@ncoghlan

This comment has been minimized.

Member

ncoghlan commented May 27, 2017

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.

@ncoghlan

This comment has been minimized.

Member

ncoghlan commented May 27, 2017

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

@ddbeck

This comment has been minimized.

Contributor

ddbeck commented May 28, 2017

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:

packaging python org-current- iphone 6
temp theadora io-pypug-pydoctheme-current html iphone 6

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.

@ncoghlan

This comment has been minimized.

Member

ncoghlan commented May 29, 2017

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.

@theacodes

This comment has been minimized.

Member

theacodes commented May 30, 2017

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. :)

@ncoghlan

This comment has been minimized.

Member

ncoghlan commented Jun 9, 2017

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
@theacodes

This comment has been minimized.

Member

theacodes commented Jun 9, 2017

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

@theacodes

This comment has been minimized.

Member

theacodes commented Jun 9, 2017

@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. :)

@theacodes theacodes force-pushed the theacodes:alabaster branch from 2fbc492 to e5de0bc Jun 13, 2017

@theacodes

This comment has been minimized.

Member

theacodes commented Jun 13, 2017

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. :)

theacodes added some commits Jun 13, 2017

@theacodes

This comment has been minimized.

Member

theacodes commented Jun 14, 2017

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

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

@theacodes theacodes changed the title from [WIP] Switch to pydoctheme to Switch to pydoctheme Jun 14, 2017

@theacodes theacodes changed the title from Switch to pydoctheme to Switch to pypa theme Jun 14, 2017

@ncoghlan

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

@theacodes

This comment has been minimized.

Member

theacodes commented Jun 15, 2017

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. :)

@theacodes theacodes merged commit 6ef0b01 into pypa:master Jun 15, 2017

1 check passed

continuous-integration/travis-ci/pr The Travis CI build passed
Details
@pradyunsg

This comment has been minimized.

Member

pradyunsg commented Jun 15, 2017

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?

@theacodes theacodes deleted the theacodes:alabaster branch Jun 15, 2017

@theacodes

This comment has been minimized.

Member

theacodes commented Jun 15, 2017

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

@pradyunsg

This comment has been minimized.

Member

pradyunsg commented Jun 15, 2017

@jonparrott Thanks! ^.^

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

@theacodes

This comment has been minimized.

Member

theacodes commented Jun 15, 2017

Yep, please do! Thank you.

@theacodes theacodes referenced this pull request Jun 15, 2017

Merged

Restore custom sidebar.js #3

ncoghlan added a commit to ncoghlan/python-packaging-user-guide that referenced this pull request Jun 24, 2017

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment