python / python-docs-theme Goto Github PK

https://docs.python.org/3/bugs.html tells me to go to bugs.python.org.
But when I did, I was told to come here.
This wastes users time, not knowing where to go.

Currently, the look of python.org is very different from that of docs.python.org. They should probably look more similar.

If nothing else, I feel at least the black top-bar for navigation with various python.org related sites should be brought over.

@freddrake repored that the searchbox is wrapping under the separation line on some screen sizes:

Since Python 3.9.6, the CHM help file has a permanent search bar at the top of the content area. When navigating to a particular location from the index or help viewer search results, the actual target location appears at the top of the content area and is covered by the search bar. This bug still exists in the CHM for 3.10rc1.

I'm not sure the presence of this search bar in the CHM help is intentional. It was added to python-docs-theme in commit 8449732 on 2021-05-07, in time for the 3.9.6 release. It cannot possibly work in CHM, and in fact, any attempt to use it leads directly to an IE error page. If it should not exist in CHM help in the first place, please disregard the rest of this bug that only describes its impact on usability.

The screenshot below was taken after double-clicking the selected index entry. You can see that the visible part of the content area starts with the first line after the method signature, but the signature itself is covered by the search bar.

The obscured strip cannot easily be made visible because there is apparently no way to scroll the content area without taking my hand off the keyboard and using the mouse to select the content area or going directly to the scroll bar.

To match most of the other https://github.com/python repos, let's use main as the default branch.

Please could @python/organization-owners rename it?

Docs here:

• https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-branches-in-your-repository/renaming-a-branch

All the relevant comments are over there https://bugs.python.org/issue28044 which got closed as soon as I added my comment, which isn't a particularly friendly sequence of events. If the issues there are outdated, they should be marked outdated and transferred here as part of the transition.

My comment is that the sidebar menus scroll off the top when you scroll down the page, so they are pretty useless, instead of helpful.

Nice implementation of sticky sidebar.
https://css-tricks.com/sticky-smooth-active-nav/#more-273952

I haven't looked at the patch, and don't know what R. David Murray doesn't like about how it works, but I find the Python sidebar extremely annoying because it scrolls off the top, and would rather it stayed around visible.

I've noticed that there's 4 releases on PyPI (2020.1, 2018.7, 2018.2, 0.0.1): https://pypi.org/project/python-docs-theme/2020.1/#history.

But in this repo there's only one tag for 2018.2 and that's it.

It's not clear what revisions were published to PyPI. It seems like this has been done using manual uploads and so I'd suggest to:

1. Find out the PyPI version to Git commit sha mappings and retrospectively tag them
2. Automate the publishing via GHA or literally anything else in order for the releases to be trackable with the logs publically available

It appears (at least for me) that the code samples and anything in a <code> tag are not rendering in their usual monospace font in versions 3.10 and above.

Tested in Chrome and Firefox - Both with a hard cache reload and cache disabled in dev tools.

3.11 screenshot (Chrome latest):

3.9 screenshot (Chrome latest):

It should be great to display a message with a link on old releases pointing to new releases.

I can imagine a banner like:

This document is about an unsupported version of Python. Please check the doc about Python 3.7.

With the "Python 3.7" text being a link to the right page on /3/, so both user and search engines can follow it.

Already been discussed here: https://bugs.python.org/issue35435

See, for example, https://docs.python.org/fr/3/tutorial/introduction.html. It applies to all interactive code examples.

This is https://bugs.python.org/issue34452, transferred here, as a third party issue. It is related to
PEP 545 - Python Documentation Translations.

Here's what I've found. The purpose of python_docs_theme/static/copybutton.js is

Add a [>>>] button on the top-right corner of code samples to hide the >>> and ... prompts and the output and thus make the code copyable.

To do this it contains code

    var hide_text = 'Hide the prompts and output';
    var show_text = 'Show the prompts and output';

Somehow, this text needs to be internationalised.

It looks like this sphinx theme package was made available on pypi, but the release there is out of date, or at least the versions don't match.

From https://bugs.python.org/issue45729

This link is empty in 3.9, 3.10 and 3.11 docs:

    {% trans pathto_license=license_file %}See <a href="{{ license_file }}">History and License</a>
    for more information.{% endtrans %}

I do not understand how these pathto_* things work and where they come from. The assignemnt looks backwards to me but it is working for other links in the same footer so it’s a bit baffling.

because the CSS has text-align: justify; on the text, and inline code is a <code> tag with a bunch of <pre> tags,

<code class="docutils literal notranslate"><span class="pre">set('abc')</span> <span class="pre">==</span> <span class="pre">frozenset('abc')</span></code>

the spaces between the <pre> tags get expanded:

https://docs.python.org/3/library/stdtypes.html#frozenset.copy

xref: pydata/pydata-sphinx-theme#247

Would a PR switching this theme to system fonts as per https://systemfontstack.com, be acceptable?

The doc is fast :)

But can it be faster ? → https://developers.google.com/speed/pagespeed/insights/?url=https%3A%2F%2Fdocs.python.org

Typically we load jquery and a few other libs, and we load them soon so they may block the rendering of the page. I think this can be enhanced, but I'm myself particularly bad at front-end things, so if someone want to handle it, go for it :)

Thanks to @JulienPalard for deploying the new theme release: https://docs.python.org/3.11/

Below 1024px, the language switcher/selector disappears.

cc/ @obulat Thought you would enjoy seeing the theme deployed. It's a great improvement.

repro:

• go to docs (Python 3.11)
• open dev console in browser
• search for e.g ."xml rpc"
  -> 404 py.svg not found

or open dev console and got to this URL directly:
https://docs.python.org/3.11/search.html?q=xml+rpc

P.S.: No 404 for the docs on 3.10

P.S.: I initially created an issue on bpo, as I was not aware there is a dedicated project for the theme. I'll close the issue at https://bugs.python.org/issue44086

It would be great to start having formal changelog, so people could easily find out what's changed without needing to read the git commit history.

The last release was https://github.com/python/python-docs-theme/releases/tag/2022.1 in January 2022.

There's been a few bug fixes merged since then:

• 2022.1...main

Notably:

• #104
• #96
• #106
• #108

My main motivation for a release is the dark theme: #44

I think it's ready for merge and release, but if we want to be safe, I suggest we make one release with the bugfixes, followed by another with the dark theme. That gives us the option to easily rollback in case there are any big issues.

cc @JulienPalard and @Mariatta :)

after installing this theme in virtual environment I've got "Theme error".
I do see "missing theme.conf" in the folder "venv/lib/python3.7/site-packages/python_docs_theme" but "make html" produces an error.
How can this error be fixed?

The code blocks of the Python docs are not using a monospace font on mobile (Android + latest Chrome). For example, this misaligns the carets of the improved errors messages in the what's new.

There is a related issue on the pythondotorg repo, but if I am not mistaken the fix could be done on python-docs-theme. There is another similar issue on the devguide repo, but I think this one has been fixed and can be closed.

Currently, it's totally unobvious just by looking at the repo that it's installable from PyPI. I'd be great to add a link in the URL field of this repo and maybe also add it (or a badge) to the README...

I have some strange issues with the monospace fonts in Vivaldi (Chrome):

(https://docs.python.org/3/library/logging.html)

Notice how the spacing is too large and numbers seem to be unicode symbols(?)

It looks fine in Firefox:

I can see there were some changes last year (#85, #87). If I change the CSS to:

tt, code, pre {
    font-family: monospace, monospace;
    font-size: 96.5%;
}

this seems to fix my issue. Having just a single monospace causes the text size to be a bit strange.

Hi team i founded on bug, Please check attached screenshot which I highlighted in it looks some text is missing it might be the alignment issue.
Alignment Issue in this page :- https://docs.python.org/3/tutorial/interpreter.html

Thanks & regards
Naveen
[email protected]

There's been interest expressed in this. This is me trying to have a dedicated place to track that whole discussion. :)

There are a bunch of options for what to do to get PR previews, to make life easier for reviewers of PRs to this theme.

The ones that I know of are:

• ReadTheDocs
• Netlify

Both of these platforms provide free hosting and the ability to preview PRs.

Ever since a responsive theme was introduced in for the 3.8+ docs (#46), one issue this theme has is that the banner "This document is for an old version of Python that is no longer supported" shows up incorrectly and behind the navbar for mobile layouts.

3.6 docs don't have this problem, since it's not using the responsive layout:

However, if I configure 3.8 docs to show this "not supported" warning, you can see the issue:

Note that this issue doesn't yet affect the docs -- it will only affect the docs once 3.8 is EOL on 2024-10-14 and the "not supported" warning is added. It does affect the efforts around deploy previews in python/cpython#92852, though, because deploy previews use the same code as the "not supported" warnings to show the "deployment preview" warnings.

This issue was originally mentioned in python/cpython#92852 (comment)

I'm stoked to see the huge improvements of the docs on mobile. This is really fantastic.

One thing I noticed, though, is that there are often huge gaps between words. For example (on Android):

Using "text-align: left" would make this look a lot better.

I would go further, and recommend to never ever use "justify" at all: it generally reduces readability and often simply looks bad. Even with wider columns it often becomes a typographic disaster (Safari, desktop):

It wasn't too clear of how to configure conf.py so that python-docs-theme will be applied.

1. Should set html_theme = 'python_docs_theme'
2. What are html_theme_option available?
3. What are html_sidebars available?

Using Firefox 88.1.3 on Android 8.1.0, screen is 1440 px wide, the version switcher is empty, and the language switcher in the menu is empty too:

1. Using the new dark theme (#44) in mobile layout: https://docs.python.org/dev/
2. Search for something (e.g. "turtle")

3. Click a result

Actual result: "Hide Search Matches" is shown subscript to the right of the search box

Expected result: It's either shown more neatly, or, like desktop view, isn't shown at all:

cc @septatrix

Please save our eyes. And batteries. Do not ignore this property of useragent https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme

Cross-defect with https://bugs.python.org/issue39518

See this screenshot for documentation that I'm writing as part of PEP 618:

The list item to the right of the cursor is awkward. I think there should be more space between it and the one above it.

I believe this commit (as part of python/cpython#23658) was intended to fix issues with the new way in which sphinx handles backslashes in the Python 3.10 documentation.

The issue is that this commit also applied to the 3.8 and 3.9 documentations, which doesn't have this new handling, and so results in escape codes (\n, \t, etc.) being escaped to just n, t, etc.
E.g. the print documentation has end='n' instead of end='\n'.

I'm guessing the files for the 3.8 and 3.9 docs just need to be reverted back to the files from before this commit.

NB: I'm not sure how the source links to different Python version's docs but the issue only applies to 3.8 and 3.9, not for the docs of Python <3.8 or >3.9.

P.S I've not used GitHub much and this is my first time delving into the python docs source so apologies if I've stated/linked anything incorrectly.

cf: pypa/pypa-docs-theme#9

Currently, this theme allows for the content to extend to the complete width of the page. This results in some extremely bad UX since essentially there are lines of text stretching across the entire width of your screen.

Limiting the width of the content would create a nicer reading experience.

The not-yet-released python 3.10 and 3.11 docs theme introduces navigation sidebar behavior that is several steps backwards in usability. From what I can tell, it exhibits all these problems:

• When open, it covers up the documentation instead of letting the text reflow, making it impossible to follow my usual workflow of quickly jumping from one section to the next while reading the bits I need. The experience is like trying to navigate around modal dialog boxes in a 1990s Windows application.
• It is now inaccessible on systems without a mouse.
• Even on computers that have a mouse, viewing it is now a hassle. One must locate the mysterious hamburger button, move a hand to the mouse, aim it at the button, and click it, before the menu will appear at all. Only then can one go about looking for a needed navigation link. That's a lot of extra steps compared to simply having the links always available at the top, bottom, or side of the page.
• Scrolling through the navigation links no longer works without a mouse. Page Up/Down, arrow keys, and space bar all fail to scroll the content being read. Only mouse navigation seems to be supported.

This new design seems to have been implemented hastily, without consideration for users outside a very narrow range of workflows and devices. Please revert it, at least until something more sensible can be developed.

When trying to run sphinx-build with -j16, I get the following warning:

WARNING: the python_docs_theme extension does not declare if it is safe for parallel reading, assuming it isn't - please ask the extension author to check and make it explicit
WARNING: doing serial read

Currently the theme is desktop only which makes the python documentation not very readable/accessible on mobile.

There was an issue on the python project created 4 years ago to address this problem.
https://bugs.python.org/issue23312

Since then the documentation theme has been separated in a different package.

I moved to python-docs-theme on my latest documentation version
and I was quite happy that it was managing body_max_width at 100% properly (cf. conf.py file).

But after a conda update, python-docs-theme goes to 2022.1 and body_max_width is no more well managed.

My configuration is:

python                    3.10.2          hc74c709_3_cpython    conda-forge
python-docs-theme         2022.1                  pypi_0    pypi
sphinx                    4.4.0                    pypi_0    pypi
sphinx-paramlinks         0.5.2                    pypi_0    pypi
sphinxcontrib-applehelp   1.0.2                    pypi_0    pypi
sphinxcontrib-bibtex      2.4.1                    pypi_0    pypi
sphinxcontrib-devhelp     1.0.2                    pypi_0    pypi
sphinxcontrib-htmlhelp    2.0.0                    pypi_0    pypi
sphinxcontrib-jsmath      1.0.1                    pypi_0    pypi
sphinxcontrib-qthelp      1.0.3                    pypi_0    pypi
sphinxcontrib-serializinghtml 1.1.5                    pypi_0    pypi

I tested, and if I re-install python-docs-theme 2021.11, the result is ok.

I have seen they did some modification on sphinx 4.4.0 on this feature ( sphinx-doc/sphinx#4246 ), but I am unable to understand the impact of this feature for python-docs-theme.

Thanks for your great work and your help ;-)

While working on the doc with @FGuillet and @BrunoMaugery we spotted some javascript updating the position of the menu, like to "pin" it on the screen while scrolling, like 2.7 is still doing. We though it was just broken, but do we want to keep this feature? It looks like it causes jiterring problems in 2.7 https://bugs.python.org/issue32393.

After reading rust-lang book, I came to python docs and man it's ugly and painful to read.
Lacking dark-mod, improper separation of heading, bad color scheme and more...

With little CSS changes, I made it more comfortable for myself,
If you agree to apply these changes to the main repo, I can send a push request.
Here is my changes:

Before:

After:

See https://bugs.python.org/issue38495

An example can be seen here https://docs.python.org/3/library/argparse.html#type. I do not know if it is the themes responsibility or if this is due to the usage of doctest on these codeblocks.

All browsers lack a margin when code block ends a section:

Compare with margin at the end of section which ends with <p> block:

All browsers set margin-top and margin-bottom on p to 1em. So the fix is setting margin-top and margin-bottom on div.highlight analogously to 1em. But I am not sure if it is to be fixed in this or in parent theme (Sphinx's classic).

div.highlight {
    margin-top: 1em;
    margin-bottom: 1em;
}

Does someone know where to fix it?

Currently the Python session code blocks has a button on top-right corner which hides the >>> and ... prompts and the output.

Would be nice to implement similar button for the shell session code blocks. It should hide the $ prompt and the output.

The current CONTRIBUTING.rst tells to bump to a dev version after releasing:

- bump version (YYYY.MM.dev) in setup.py and python_docs_theme/theme.conf
- Commit this last bump.
- push and push the tag (``git push && git push --tags``)

Is it really usefull? I don't contribute a lot to this repo and I don't feel it's usefull for me, but if it's usefull for you please tell.

@willingc I don't remember why it's here, git log tells it's me but I think I copy-pasted this sequence of tasks from way before me, mabe you gave it to me and you now better?

Hi, can we get a release of this with the latest fixes? In particular, we're getting reports about the broken Sphinx link in the footer.

If there's anything I can do to help it along, please let me know.

Compare 3.9 vs 3.10:

See python/cpython#21376 (comment) though that change isn't what actually causes this, it seems to be the case on all documentation pages that I checked.

Today I'm seeing a theming issue:

It looks like cache problem, so I'm going to investigate step by step...

...damned, opening the Firefox console solved the issue (the no-cache were ticked), so we have a browser cache issue: users with the old theme in their local cache may get what I got.

I unticked the Firefox network console "disable cache" and tried all other translations to try to reproduce, and was able to reproduce it once:

The request done by my browser was:

curl 'https://docs.python.org/zh-cn/3.10/_static/pydoctheme.css' -H 'User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:88.0) Gecko/20100101 Firefox/88.0' -H 'Accept: text/css,*/*;q=0.1' -H 'Accept-Language: fr,en-US;q=0.7,en;q=0.3' --compressed -H 'DNT: 1' -H 'Connection: keep-alive' -H 'Referer: https://docs.python.org/zh-cn/3.10/library/functions.html' -H 'Sec-GPC: 1' -H 'TE: Trailers'

(Which, using curl, give the up-to-date file)

But got no response (first time I see this) it were "raced" (by the local cache?) I only see 882 B (raced) in the network pane, no more info.

According to https://support.mozilla.org/en-US/questions/1267945 this display mean the network won the race, which looks wrong because I have no response header and the css is the old one:

Also the size is too low to contain the whole css, so it looks like the network connection has started, bytes has been received, but the cache won the race and the network connection was interrupted.

Which I find strange is that when I refresh, all other components are requested by my browser, which all properly receive a "304 not modified" answer, but not the CSS itself:

I'd like a release with #14 (already merged, just not released), as it fixes a warning in the build process and I'd like to enable "-W" (turn warning to errors) in the french translation.

Can one (having the rights to do it) release it?

I tested it locally and current master works for me.