Skip to content
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

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

Closed
jakirkham opened this issue Apr 12, 2022 · 28 comments
Closed

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

jakirkham opened this issue Apr 12, 2022 · 28 comments
Assignees
Labels
docs Documentation in the Doc dir type-bug An unexpected behavior, bug, or error

Comments

@jakirkham
Copy link

jakirkham commented Apr 12, 2022

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:

Screen Shot 2022-04-12 at 1 09 06 PM

@JelleZijlstra
Copy link
Member

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?

@JelleZijlstra JelleZijlstra added the docs Documentation in the Doc dir label Apr 12, 2022
@AlexWaygood AlexWaygood added the type-bug An unexpected behavior, bug, or error label Apr 12, 2022
@AlexWaygood
Copy link
Member

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

@saaketp
Copy link

saaketp commented Apr 12, 2022

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

@jakirkham jakirkham changed the title [DOC] Warning in pickle docs including most of the page [DOC] Warnings/notes in docs including most of the page Apr 12, 2022
@jakirkham
Copy link
Author

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

@AlexWaygood
Copy link
Member

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

@jakirkham
Copy link
Author

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?

@JulienPalard
Copy link
Member

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.

@JulienPalard
Copy link
Member

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

@AlexWaygood
Copy link
Member

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

@JulienPalard JulienPalard pinned this issue Apr 13, 2022
@JulienPalard
Copy link
Member

JulienPalard commented Apr 13, 2022

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

Done, hope it'll help.

@JulienPalard
Copy link
Member

I rebuilt all english docs. Rebuilding other docs now.

@AlexWaygood
Copy link
Member

I rebuilt all english docs. Rebuilding other docs now.

Thanks @JulienPalard — I can confirm that I no longer see the problem for the 3.10 docs for typing or pickle, either on Opera on my phone or Safari on my iPad.

@jakirkham
Copy link
Author

Yep LGTM as well. Should we close or should this remain open?

@AlexWaygood
Copy link
Member

AlexWaygood commented Apr 13, 2022

Yep LGTM as well. Should we close or should this remain open?

I'd let @JulienPalard make that decision — I think he may be leaving it open until it's confirmed that the other languages are okay as well

@JulienPalard
Copy link
Member

I'll close this when all languages and all versions gets fully rebuilt. I fear if we close it now, some other duplicates may appear.

@JulienPalard
Copy link
Member

Complete HTML rebuild done, everything should be fixed now. Thanks @jakirkham for the heads up!

@JulienPalard JulienPalard unpinned this issue Apr 13, 2022
@jakirkham
Copy link
Author

Thanks Julien! 🙏

@saaketp
Copy link

saaketp commented May 25, 2022

The docs are broken again it seems?
I can see those colors filling the whole page again.
https://docs.python.org/3/library/typing.html
https://docs.python.org/3/library/pickle.html
https://docs.python.org/3/library/string.html

@AlexWaygood AlexWaygood reopened this May 25, 2022
@AlexWaygood
Copy link
Member

The docs are broken again it seems? I can see those colors filling the whole page again. https://docs.python.org/3/library/typing.html https://docs.python.org/3/library/pickle.html https://docs.python.org/3/library/string.html

(Cc. @JulienPalard)

@JulienPalard
Copy link
Member

Looks like the venv did not get build properly (I though https://github.com/python/docsbuild-scripts/blob/ac1adcb83baf60261f243a74dab1fd4b9fc6bbf7/build_docs.py#L113 would have been enough).

I installed the right docutils version and restarted an html-only build of 3.10, it should be fast to fix at least /3/.

I hope I'll have time to inspect/understand this in more details in a few hours or tomorrow.

@JulienPalard
Copy link
Member

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.

@Kenny2github
Copy link
Contributor

Kenny2github commented Aug 3, 2022

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.

@AlexWaygood
Copy link
Member

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

@hauntsaninja
Copy link
Contributor

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

@gvanrossum gvanrossum unpinned this issue Aug 7, 2022
@AlexWaygood
Copy link
Member

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

@bharel
Copy link
Contributor

bharel commented Aug 7, 2022

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.

@JelleZijlstra JelleZijlstra pinned this issue Aug 7, 2022
@gvanrossum
Copy link
Member

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

@JulienPalard
Copy link
Member

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.

@erlend-aasland erlend-aasland unpinned this issue Aug 8, 2022
JulienPalard pushed a commit to python/docsbuild-scripts that referenced this issue Aug 21, 2022
It appears that the venv keeps breaking: python/cpython#91483

I'm not sure how to best help investigate, but adding some more logging seems like it could be useful :-)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docs Documentation in the Doc dir type-bug An unexpected behavior, bug, or error
Projects
None yet
Development

No branches or pull requests

10 participants