[DOC] Warnings/notes in docs including most of the page

Edit: This was originally notes with the pickle docs, but has also been seen on other pages since. Updating the issue to reflect that.

Not sure if something changed recently with how the docs are being generated, but it appears the warning at the top of the pickle docs is including most of the doc page in the warning. This is picking up all of the APIs and example as a result. Screenshot below:

That's nasty. I see it in the 3.9 and 3.10 docs, but not 3.11 or 3.8. pickle.rst hasn't changed on the 3.10 branch since December 2020 (GH-23658), so it's probably not a change to the file. Maybe a Sphinx issue?

@JulienPalard

@JulienPalard, any ideas on what might be causing this one? 😕

It is not just the pickle page.
The string docs are all yellow too https://docs.python.org/3/library/string.html
Only the "see also" box should have been yellow.

Maybe any page with a colored box is getting filled with that color.

edit: found another page that confirms this:
the hashlib docs https://docs.python.org/3.10/library/hashlib.html

Thanks for sharing that! Updated the issue to reflect it is broader than its original scope.

Ugh, the same thing with the typing docs too, now the whole page has a grey background (it should be just the first paragraph).

Do the docs build on CI somewhere? Maybe we can diff requirements between the last known working build and the current one to see what may have caused the issue?

Found it.

I introduced the issue while removing and re-creating the build venvs on docs.python.org yesterday after python/psf-salt@ca491a3 to close python/docsbuild-scripts#126.

The new venv got a new version of docutils (we were having 0.17.1, we now have 0.18.1).

Looks like there's some incompatiblity between Sphinx 3.2.1 and docutils 0.18.1, so I'm pinning this version in docsbuild-scripts.

I'll start a rebuild of docs.python.org HTML files in a few minutes and we'll see how it goes.

Looks like it resolved the issue: https://docs.python.org/fr/3.9/library/pickle.html

Rebuilding all languages for all versions may take a few ... hours though :)

@JulienPalard

@JulienPalard @JelleZijlstra, can somebody pin this issue while the docs are rebuilding? We've had 2 duplicates in 10 minutes

I checked, it's fixed on d.p.o but I don't have time to dig right now, please leave the issue open until this is understood.

Seeing this again in the docs for json, csv, threading, pickle, string, hashlib, typing, and probably others.

Looking at the HTML source of typing:

<div class="admonition note">
<p class="admonition-title">Note</p>
<p>The Python runtime does not enforce function and variable type annotations.
They can be used by third party tools such as type checkers, IDEs, linters,
etc.</p>
</aside>

It seems like admonitions are being opened as <div>s but closed as </aside>s. This is causing the <div> to not close and thus wrap the whole page.

Note that these are broken only on 3.10 docs; 3.9 are fine.

@JelleZijlstra

@JelleZijlstra could you possibly pin this issue, since this is happening again? We're getting a ton of duplicates at the moment :(

Run pip freeze after installing requirements

Not sure who all have permissions on the docs setup, but I proposed a fix here: python/docsbuild-scripts#133

@gvanrossum

@gvanrossum, did you mean to unpin this issue? :) it's still an ongoing problem, and we just got another duplicate filed :(

Was about to file another duplicate. It's hard to find this issue while all others are getting closed, especially when it's old and doesn't show on top of the issue tracker.

@gvanrossum

@gvanrossum, did you mean to unpin this issue? :) it's still an ongoing problem, and we just got another duplicate filed :(

Sorry, I didn't mean to. I was just confused by what to me appeared to be a random issue linked at the top of some GitHub page. Maybe a pinned issue should be custom-made to have text alerting people to a something? I honestly didn't understand why this issue was important enough to be pinned.

@hauntsaninja

Sorry for the delay, I'm currently having a very limited internet connectivity (and time) so I'm not following closely those issues.

I merged python/docsbuild-scripts#133, I don't know exactly at which version of Sphinx the issue has been fixed but it should do, thanks @hauntsaninja (if someone have the time to look at it more closely, it would be appreciated).

I also manually restarted a build of 3.10 (English only, HTML only) to check if everything gets fixed (and it is \o/).

More specifically I ran:

cd /srv/docsbuild/
./venv-with-sphinx-3.4.3/bin/python -m pip install 'docutils<=0.17.1'
/srv/docsbuild/venv/bin/python /srv/docsbuild/scripts/build_docs.py --branch 3.10 --languages en --quick

I'm now running (in a GNU screen):

/srv/docsbuild/venv/bin/python /srv/docsbuild/scripts/build_docs.py --branch 3.10 --quick

for other languages to get fixed, and I'm shutting down my internet connectivity, hoping for the best.

Run pip freeze after installing requirements (#132)

Navigation Menu

Repository navigation

[DOC] Warnings/notes in docs including most of the page #91483

15 remaining items

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

[DOC] Warnings/notes in docs including most of the page #91483

Description

Activity

JelleZijlstra commented on Apr 12, 2022

AlexWaygood commented on Apr 12, 2022

saaketp commented on Apr 12, 2022

jakirkham commented on Apr 12, 2022

AlexWaygood commented on Apr 12, 2022

jakirkham commented on Apr 12, 2022

JulienPalard commented on Apr 13, 2022

JulienPalard commented on Apr 13, 2022

AlexWaygood commented on Apr 13, 2022

15 remaining items

JulienPalard commented on May 25, 2022

Kenny2github commented on Aug 3, 2022

AlexWaygood commented on Aug 3, 2022

hauntsaninja commented on Aug 6, 2022

AlexWaygood commented on Aug 7, 2022

bharel commented on Aug 7, 2022

gvanrossum commented on Aug 7, 2022

JulienPalard commented on Aug 7, 2022

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions