Add support for "scope" option

[Bizordec]

Didn't find where to set the "scope" option, so here it is.

[2bndy5]

What does exposing this accomplish? I think the doc entry could be explained more. Is there info about this in the mkdocs-material theme?

[Bizordec]

It's useful in case when you build subsites separately. For example, for this structure

.
└── /
    ├── A/
    ├── B/
    └── C/

each site will have its own state for palette (/A/.palette, /B/.palette, /C/.palette). To share the same state between all subsites, you could set "scope": "/".

In mkdocs-material it's somehow still not documented, but here's the description in this issue: squidfunk/mkdocs-material#1914 (comment)

[2bndy5]

This seems useful for different versioned sets of docs. We do support custom cookies, but that's another feature that has gone undocumented here.

How have you tested this?

[Bizordec]

Added test and better description.

I've also created a PR in mkdocs-material (squidfunk/mkdocs-material#5967), guess it'll soon be documented there too 😃

satisfied

[2bndy5]

I should add nox info to our contributing guidelines.

[2bndy5]

I've re-run the CI multiple times, but the docs build on the windows runner fails to download/cache the fonts from google's API:

http.client.RemoteDisconnected: Remote end closed connection without response

This is specific to this PR, but I just wanted to pass that along. 🤷🏼‍♂️ I'm starting to see this in other PR's CI runs...

[Bizordec]

I think i've fixed that SSL problem by adding some pypi packages.
https://stackoverflow.com/a/46467942
https://github.com/Bizordec/sphinx-immaterial/actions/runs/6137800799

[2bndy5]

I was starting to suspect

1. the google server was changed
2. the Google API key we use to fetch fonts maybe outdated (🤷🏼‍♂️)

[Bizordec]

Okay, it failed again... I don't get it... Is it possible to somehow reset this runner?
Oh, wrong requirements.txt

[2bndy5]

Actually, I think the answer should be a short-lived cache of the fonts per CI run (specific to each OS). Currently, each unit test and docs build we do re-downloads the same sets of font families.

[jbms]

We could cache if necessary but it does add some complications. The failing requests seem to be the plain requests to retrieve individual fonts. Those requests do not use an API key and occur anytime someone loads a page that uses Google fonts --- i.e. expected to get a lot of traffic.

I see that the CI is still failing, despite what was intended to fix it?

[jbms]

Does it always fail with Python 3.11 on Windows, or is it random?

[2bndy5]

It seems to be specific to windows runner, but I've seen it happen on macos too. Caching the fonts only ensures the tests can exec without re-downloading the fonts (saves a few seconds per job) -- see #292 CI runs.

I think it is specific to py v3.11 too.

[Bizordec]

And now windows build failed even before creating a font cache 😕

[2bndy5]

I've been starting to see the google fonts problem downstream in my sphinx-social-cards ext CI (specific to windows and mostly python v3.11).

In researching the possible problems, I noticed google fonts has a newer API to support variable fonts: https://developers.google.com/fonts/docs/css2. Could be worth a try (for fixed fonts), but I don't think variable fonts are supported in this theme.

[2bndy5]

Maybe this change in py3.11.5 might have something to do with the SSLEOFError we keep seeing on the windows runners. v3.11.5 was released Aug 24 2023.

[2bndy5]

I'm unable to reproduce this SSLError locally with Windows 11 + Python v3.11.5.

[Bizordec]

Python v3.11.6 just got released, maybe it will fix the issue
https://docs.python.org/release/3.11.6/whatsnew/changelog.html#python-3-11-6

Tools/Demos
gh-109991: Update GitHub CI workflows to use OpenSSL 3.0.11 and multissltests to use 1.1.1w, 3.0.11, and 3.1.3.

[2bndy5]

Unfortunately, the actions/setup-python still uses 3.11.5 as the latest.

I am eager to see if this was identified and fixed though.

[2bndy5]

@jbms Any objections to merging this? I'd like to get this merged so I can push a tag and release the changes labeled "pending release"

@Bizordec Thank you so much for your patience and work (& rebasing) here!

[Bizordec]

Oh wow, build have finally passed! Although v3.11.5 was used 🤷‍♂️
Glad to help! 😄

[2bndy5]

It would seem that the github actions runners on windows have a cached version of python. Among the caches is python 3.11.5 (no later), so we either wait until the windows runner image is updated (takes a long time on purpose) or we explicitly tell actions/setup-python to download the latest version from github releases of actions/python-versions.

[2bndy5]

I still hit the SSLError in CI using python 3.11.6 on Windows (on a different repo using this theme in unit tests and docs builds). I think this might be more specific to google fonts API (probably a combination of py 3.11+ and google fonts API).

[2bndy5]

actions/setup-python now uses v3.12.0 as the latest python version:

[2bndy5]

released with v0.11.8