Make the theme responsive by obulat · Pull Request #46 · python/python-docs-theme · GitHub

I have been reading on my phone a lot lately, and was disappointed by the fact that I couldn't read python docs: the fonts are too small, and, if I try to zoom in, the text doesn't fit on the page, so I have to swipe to see the whole line.

This is my attempt to add responsiveness to python docs theme, fixing #30.

On screen widths smaller than 900 px, it:

adds a mobile navigation bar with a 'hamburger' menu button, Python version switcher and a search box.
adds a sliding menu that opens when 'hamburger' menu button is clicked. Menu contains language switching input and contents.
removes the related bars
removes the sidebar.

Screenshot with menu closed:

Screenshot with menu open:

Problems that need to be solved:

Normally, the mobile navigation bar should be placed in the header block of the layout, but python.org layout completely overrides it, so I added it in the body_tag block. To solve this, I would need to add changes to that code.
I placed the switchers and other items on the menus as seemed logical to me, but feedback from the community is essential on this.
I added a javascript file to open/close sidebar in a separate file. I could also add it into the layout file, but ideally all js files should be combined and minified.

Overall a great idea and I would also really like a responsive theme though there seem to be some unrelated changes and implementation details which should be discussed

By moving the checkbox up in the dom tree it may be possible to implement this using only javascript and make it more accessible for people without javascript

I replaced the checkbox with a button. Is this better for people without javascript?

What I would have done is move the input as a checkbox directly next to the sidebar, reference it in the label via id and apply the styles based on whether the checkbox is checked or not. I may have time tomorrow to create a PR on your fork repo if you want to.

I have done it like this at first (checkbox input and applying styles based on :checked property). Then I was checking for accessibility and found this article which shows that a button as menu opener has some advantages regarding accessibility: namely, it is easier to set up keyboard handling. On the other hand, I just realized that people probably don't use keyboard for navigation on mobile, and it is more important to set up No-script solution than keyboard navigation on mobile.
Also, I looked at other documentation sites: readthedocs theme and VueJS docs, and their hamburger menu doesn't work without javascript.

In addition if you follow this guide you also get a working css only solution with added accesibility using javascript

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.

- Remove unnecessary `show` call for searchbox. - Remove `box-sizing:border-box` for all elements. - Add `aria-label` to search input instead of visually-hiding labels for accessibility - Some style fixes

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.

- Menu is opened/closed using only css (invisible checkbox), works without js enabled - Accessibility added using javascript

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.

If possibly I would stay with the sphinx default of not modifying the box-sizing property

I tried removing it, but I couldn't get the searchbox to fit the screen on all the different sizes: flexbox and padding and border in content-box sizing model are too complex. I don't think adding a different box-sizing property should be a problem because the new box-sizing applies only to the .mobile-nav part.

FWIW, I don't see any reason to avoid doing this, as long as whoever works on this theme finds that model easier to work with. There are variants of normalise.css that set this on the entire page, so setting this for a whole bunch of elements, is A-OK in my opinion.

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

pathto(master_doc) would be more appropriate here?

Or does CPython documentation use contents for the toctree?

Thank you for such a quick review! :) I know what I added doesn't work for sure. Let me try pathto(master_doc).

I need help!
I don't know how to add the correct link to the docs.python.org/3.9/.
In line 88 in layout.html I added <a href="{{ pathto(theme_root_url) }}" , and it creates file:///.../doc-html(3)/3.9/https://www.python.org/.html

Don't wrap it in pathto, just {{ theme_root_url }} is enough.

That should fix it. :)

In other words, that is behaviour I'd expect and I thought that's what you wanted?

I guess I was confusing the two kind of links (to the docs home and the language/framework home). On the sites I used a lot lately (eg Vue.js) the style of the framework home page and the style of the documentation homepage are the same. And it feels like I just go to the documentation home, not the general home, when I click on the logo.

But you are right, now we have the correct behavior, linking to python.org.

We still don't have a way of going to the documentation homepage, docs.python.org/3 from other pages on mobile. Is it necessary to add it, and add it in this PR specifically?

If you want to have a link to the documentation homepage, that'd be {{ pathto(master_doc) }} or {{ pathto("index") }}. No need for a |e on either of them.

Honestly, this feels like something we can do in a follow up PR.

I'd really like to push for getting this landed soon, so that we can start moving other things forward without needing to come back and update this.

Please, let me know if I need to change anything? I would be happy to get this landed soon, 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.

The CSS in the base template was updated to include this directive in #7695 and released in sphinx v3.1.0. The original implementation was in python#46, prior to the basic theme including it, and now we have the same meta tag duplicated. Remove the block, and reduce the duplication. Signed-off-by: Mike Fiedler <miketheman@gmail.com>

Make theme responsive

7aba474

the-knights-who-say-ni added the CLA signed label May 19, 2020

septatrix suggested changes Jun 14, 2020

View reviewed changes

Address code review issues

203b40a

- Remove unnecessary `show` call for searchbox. - Remove `box-sizing:border-box` for all elements. - Add `aria-label` to search input instead of visually-hiding labels for accessibility - Some style fixes

JulienPalard mentioned this pull request Jun 21, 2020

bpo-41028: Doc: Move switchers to docsbuild-scripts. python/cpython#20969

Merged

Use css for opening/closing menu

10f4349

- Menu is opened/closed using only css (invisible checkbox), works without js enabled - Accessibility added using javascript

septatrix reviewed Sep 20, 2020

View reviewed changes

Comment thread python_docs_theme/static/pydoctheme.css Outdated

septatrix reviewed Sep 20, 2020

View reviewed changes

pradyunsg mentioned this pull request Oct 19, 2020

WIP: Switch to Furo pypa/pip#9012

Merged

JulienPalard mentioned this pull request Dec 13, 2020

Extremely poor docs.python.org SEO performance. python/docs-community#179

Open

Adjust font and selects

ff61d60

Add language and version switcher placeholders

7640739

obulat added 2 commits May 5, 2021 14:31

Add link to homepage in mobile version

190931b

Add smaller padding to toctree

b6fc448

pradyunsg reviewed May 5, 2021

View reviewed changes

obulat added 4 commits May 5, 2021 15:11

Add a different link to the logo

cd92c8c

Make logo in mobile version link to 'http://0.0.0.0:8000/3.9/'

ed7b948

Make logo in mobile version link to 'http://0.0.0.0:8000/3.9/'

d96713e

Make logo in mobile version link to theme root

bd1d802

willingc approved these changes May 7, 2021

View reviewed changes

JulienPalard approved these changes May 7, 2021

View reviewed changes

pradyunsg approved these changes May 7, 2021

View reviewed changes

FGuillet approved these changes May 7, 2021

View reviewed changes

JulienPalard merged commit 8449732 into python:master May 7, 2021

hugovk mentioned this pull request Jun 21, 2021

Improve favicons to match www.python.org #56

Closed

epicfaace mentioned this pull request Jun 19, 2022

Documentation with responsive theme (3.8+) will hide "not supported" banner behind navbar for mobile layouts #95

Closed

philg314 mentioned this pull request Aug 1, 2022

Search box is wrapping when screen size is reduced #7

Closed

hugovk mentioned this pull request Jan 31, 2023

Fix: searchbox is wrapping under the separation line for screen sizes #33

Closed

hugovk mentioned this pull request Jul 27, 2023

The 3.10 documentation has a horizontal scroll bar on mobile #65

Closed

hugovk mentioned this pull request Jan 28, 2025

Make the sidebar resizable #214

Closed

+              document.addEventListener('DOMContentLoaded', function () {
+                  const toggler = document.querySelector('.toggler');
+                  const sideMenu = document.querySelector('.menu-wrapper');
+                  const doc = document.querySelector('.document');
+                  function closeMenu() {
+                      sideMenu.classList.remove('open');
+                      toggler.checked = false;
+                  }
+                  toggler.addEventListener('change', function (e) {
+                      if (toggler.checked) {
+                          sideMenu.classList.add('open');
+                      } else {
+                          closeMenu();
+                      }
+                  });
+                  doc.addEventListener('click', function () {
+                      if (toggler.checked) {
+                          closeMenu();
+                      }
+                  })
+              })

                
                    No newline at end of file

                   </label>
                   <nav class="nav-content" role="navigation">
-                      <img src="{{ pathto('_static/' + 'py.svg', 1) }}" alt="Logo"/>
+                       <a href="{{ pathto('index') }}">

+                      z-index: 1;
+                  }
+                  .mobile-nav * {
+                      box-sizing: border-box;

Make the theme responsive by obulat · Pull Request #46 · python/python-docs-theme · GitHub

Repository navigation

Make the theme responsive - #46

Make the theme responsive#46JulienPalard merged 24 commits intopython:masterpython/python-docs-theme:masterfrom obulat:masterobulat/python-docs-theme:masterCopy head branch name to clipboard

Conversation

obulat commented May 19, 2020

Problems that need to be solved:

Uh oh!

septatrix left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

obulat commented Jun 14, 2020

Uh oh!

JulienPalard commented Jun 20, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

JulienPalard commented Jun 21, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

obulat commented Jun 22, 2020

Uh oh!

septatrix commented Jun 23, 2020

Uh oh!

obulat commented Jul 12, 2020

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pradyunsg commented Nov 9, 2020

Uh oh!

obulat commented Dec 20, 2020

Uh oh!

pradyunsg commented Dec 20, 2020

Uh oh!

septatrix commented Dec 20, 2020

Uh oh!

obulat commented Dec 21, 2020

Uh oh!

obulat commented Dec 21, 2020

Uh oh!

JulienPalard commented Dec 23, 2020

Uh oh!

JulienPalard commented Dec 23, 2020

Uh oh!

obulat commented Dec 23, 2020

Uh oh!

obulat commented Dec 23, 2020

Uh oh!

JulienPalard commented Dec 24, 2020

Uh oh!

obulat commented Dec 25, 2020

Uh oh!

pradyunsg commented May 3, 2021

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Make the theme responsive#46
JulienPalard merged 24 commits into
python:masterfrom
obulat:master

JulienPalard commented Jun 20, 2020 •
edited
Loading

JulienPalard commented Jun 21, 2020 •
edited
Loading

pradyunsg May 5, 2021 •
edited
Loading

pradyunsg May 5, 2021 •
edited
Loading

pradyunsg May 5, 2021 •
edited
Loading