GeezerVison

Thank you for your review, @septatrix !
I don't have a reliable internet connection at the moment, but will try to address your comments as soon as possible. Overall, I have tried to make the theme accessible as well as responsive, that's the reason for some label handling. Also, I tried to use only Vanilla javascript to make it easier to remove jquery dependency in the future.

I would also like to have your feedback on the content for the mobile version. For example, the top navbar on mobile: Do you think logo, version switcher and searchbox are what should be there, or do we need to add/ remove something?

Also, the relbar is completely removed, but I thought that it might be a good idea to add it at the bottom, without the searchbox, though.

Beware, i'm working on moving the switchers generation code to docsbuild scripts instead of cpython. See python/docsbuild-scripts#90

I did not think about switchers being located in different places, we have to check if there is something to fix either in docsbuild side or here.

As the switchers are no longer to be maintained in cpython, I was removing the placeholders and the switchers variable in python/cpython#20969

I'm on my phone right know so I can't test it, but we need to agree on how to "communicate" to docsbuild the switchers places.

Hi @obulat!

Took the time to think about it, but beware, I'm particularily bad at HTML/JS:

• python-docs-theme is not cpython specific, it can be used elsewhere, that's typically why the "This document is for an old version of Python" header is in cpython and not in the theme.
• Switchers are not cpython specific: other documentations can be translated and have versions.
• The classes .version_switcher_placeholder and .language_switcher_placeholder has always been in use and looks good to me.
• Having multiple version placeholders may work, IIRC, jquery will properly create them all when I do $('.version_switcher_placeholder').html(version_select);

The current switchers.js, the one from docsbuild-scripts has two ways of working (see function create_placeholders_if_missing):

• Either there's a '.version_switcher_placeholder' and it uses it (typically when cpython or the theme places it)
• Either there's not, and it tries it best to find a place to create both placeholders (side by side), see the ugly probable_places array (I may soon add a cleaner cpython-language-and-version in front of it, but it may not be usefull if you handle it in the theme).

What about adding all needed placeholders in python-docs-theme, so switchers.js from docsbuild-scripts could rely on them, instead of trying to inject HTML? In "mobile version" it currently injects them in HTML that is not rendered, so no switchers appear.

How to test with docsbuild-script locally:

$ # In a clone of docsbuild-scripts
$ mkdir -p www logs build_root
$ python3 -m venv build_root/venv/
$ build_root/venv/bin/python -m pip install -r requirements.txt
$ build_root/venv/bin/python -m pip install path_to_your_python-docs-theme
$ python3 ./build_docs.py --quick --build-root build_root --www-root www --log-directory logs --group $(id -g) --skip-cache-invalidation --language en --branch master

(Currently testing it and wow, that's really nice, thanks a lot for working on this topic!)

Hi, @julien, thank you for your comments, that's really helpful!

I will try to look into it as soon as I have time.

I think a problem which should be tackled first is overflowing stuff like tables, all dt for definitions as well as code segments inside the docs. These are for the most part not broken an lead to a wider page than intended. Together with the addition of the <meta name="viewport" ...> tag this will already solve most problems. This way no major design changes would be necessary as the sidebar should actually also work great on mobile devices (maybe make it a few pixels wider). The problem with the header/footer wrapping badly due to its floating nature already happens for me at around 1200px width.

I think a problem which should be tackled first is overflowing stuff like tables, all dt for definitions as well as code segments inside the docs. These are for the most part not broken an lead to a wider page than intended. Together with the addition of the <meta name="viewport" ...> tag this will already solve most problems. This way no major design changes would be necessary as the sidebar should actually also work great on mobile devices (maybe make it a few pixels wider). The problem with the header/footer wrapping badly due to its floating nature already happens for me at around 1200px width.

I've added wrapping tables in a div that can be horizontally scrolled: this is the solution used in readthedocs. dt and code segments are already horizontally scrollable.

Wheee! This is amazing. Is there anything I can do to help move this forward? :)

Hi, should I close this issue due to the new theme added in pypa/pip#9012 ?

@obulat No no. I don’t imagine docs.python.org would be changing to that theme anytime soon, and this PR is a pretty great improvement over status quo.

And even if the theme were to change there may still be other projects using this theme

What about adding all needed placeholders in python-docs-theme, so switchers.js from docsbuild-scripts could rely on them, instead of trying to inject HTML? In "mobile version" it currently injects them in HTML that is not rendered, so no switchers appear.

Hi, @JulienPalard ,

I'm on Windows, so originally I couldn't test the docsbuild-scripts steps because they wouldn't run. Now, I tried running them on my Ubuntu (Windows Subsystem for Linux), but I couldn't get my local version of the theme to apply.

However, I did add empty placeholder divs: .version_switcher_placeholder in the top navbar, and .language_switcher_placeholder in the left menu.
Could you please test it?

I'm sorry it took me so long to get back to implementing the requested changes.
@pradyunsg , thank you for your comments!

The index page still doesn't look too good, with the main reason being that the layout used for contents is a table, which doesn't look good on a small screen. I think we should convert it into a two-column layout that can be converted into a one-column layout on smaller screens. However, I would say it is a to-do for another PR.

I'm on Windows, so originally I couldn't test the docsbuild-scripts steps because they wouldn't run.

There's no Windows support on docsbuild-scripts, and I don't except to add it anytime.

Now, I tried running them on my Ubuntu (Windows Subsystem for Linux), but I couldn't get my local version of the theme to apply.

This is really strange, can you open an issue on docsbuild-script with the steps you followed so I can try reproduce and we fix this? I often build the docs locally (on Debian), and have no theme issues.

@obulat I was able to build a local version, I had to patch docsbuild-scripts (hardening a regex detecting the version part in the URL in case the URL contains an IP like 0.0.0.0 ...).

It works: it gets replaced \o/ but only on mobile, as the placeholder only exist for mobile.

There's no Windows support on docsbuild-scripts, and I don't except to add it anytime.

I completely understand, just wanted to add this bit of information for context.

This is really strange, can you open an issue on docsbuild-script with the steps you followed so I can try reproduce and we fix this? I often build the docs locally (on Debian), and have no theme issues.

I will try to do that as soon as I can.

@obulat I was able to build a local version, I had to patch docsbuild-scripts (hardening a regex detecting the version part in the URL in case the URL contains an IP like 0.0.0.0 ...).

It works: it gets replaced \o/ but only on mobile, as the placeholder only exist for mobile.

As this PR is for the mobile version, I did not touch the placeholders for the desktop version. I could add them here, or in a new PR.

As this PR is for the mobile version, I did not touch the placeholders for the desktop version. I could add them here, or in a new PR.

I can understand, but this is a bit dangerous: if there's a release between your two PRs, language and version switchers will disaperar on desktop (as paceholders are found on the new mobile part, my code don't try to add them on the desktop part).

I mean, in switchers.js I have two branches : either the placeholders are found and I use them, or they are not found and I create them, so if they're found, they're not created.

I can understand, but this is a bit dangerous: if there's a release between your two PRs, language and version switchers will disappear on desktop (as placeholders are found on the new mobile part, my code don't try to add them on the desktop part).

I didn't realize that. I tend to include too much in my PRs, so I was trying to improve myself 😄

I added the placeholders.

The plan sounds good to me! And, as I'm probably over-stating now, we can iterate too! :)

LGTM. @pradyunsg if it's OK for you too, I'm ok for a merge :)

Way to go @obulat 🎉 🐍! Thanks for the great teamwork @JulienPalard and @pradyunsg. Happy to see this merged soon 👍🏼

Thank you everyone! I'm really excited for this change!

Thanks a lot @obulat, I hope this can go to production soon. @willingc do you know the release process?

I don't have the upload rights to pypi/p/python-docs-theme.

I don't @JulienPalard, but I can look into it tomorrow.

Thanks also from me - when I originally put together this theme I hadn't even expected it to live so long :D

@Mariatta @ncoghlan @theacodes If one of you can deploy this awesome update or give @JulienPalard or me privileges that would be great. Would love to see @obulat's work in production 🎉

@birkenfeld Thank you for all that you have done for docs over the years. You rock. 🎉

@willingc you now have permissions on PyPI ✨

If there are already so many people taking a look at this right now I would like to mention the dark theme PR which also is ready for review

@septatrix I just saw this now. After the dark theme lands we can do a dot release to get that in.