doc: add social cards generation support in sphinxext-opengraph

[FFY00]

https://github.com/wpilibsuite/sphinxext-opengraph/blob/d557f8d27fda106a4ebcb6921ce9b278b724938c/sphinxext/opengraph/__init__.py#L12-L19

---

📚 Documentation preview 📚: https://cpython-previews--129085.org.readthedocs.build/

[hugovk]

I don't quite the IS_PYTHON_BUILD logic here, is this only meant to generate the social images when the Python is built from source, and not for actual docs deploys to the website?

See also python/docsbuild-scripts#147 where I considered this two years ago, where I had concerns about it generating (at the time) 482 images and 41 MB, multiplied by all the languages and versions.

cc @AA-Turner

[hugovk]

And also --only-binary means matplotlib isn't installed for main because there's no 3.14 wheels at https://pypi.org/project/matplotlib/#files

[AA-Turner]

Thanks for the tag Hugo, I missed this PR as it didn't have the docs tag.

I'm likewise unsure about what this is meant to achieve, if we want to generate the opengraph preview images then we should enable it via docsbuild-scripts rather than here. I'd perhaps suggest reverting this PR?

A

[AA-Turner]

See also #101639, #101642, and #125264 where we tried only-binary for a different package, but went with python/docsbuild-scripts#217 instead.

A

[AA-Turner]

I've opened #129106 as a proposal for a clean revert, and I've been working with Hugo to try and set up preview images through docs.python.org.

A

[FFY00]

I don't quite the IS_PYTHON_BUILD logic here, is this only meant to generate the social images when the Python is built from source, and not for actual docs deploys to the website?

No, the opposite.

We don't want to try to install matplotlib on source builds since it's a native extension, and it wouldn't be a good idea to try to build it against a development CPython version.

We don't use the Python build from source to deploy the website, so the missing optional dependency doesn't really matter there. This patch makes the dependency available on our docs deployment job, which is what we really care about.

[FFY00]

I'm likewise unsure about what this is meant to achieve, if we want to generate the opengraph preview images then we should enable it via docsbuild-scripts rather than here. I'd perhaps suggest reverting this PR?

Ah, gotcha, I guess I was under the incorrect impression.

[hugovk]

I don't quite the IS_PYTHON_BUILD logic here, is this only meant to generate the social images when the Python is built from source, and not for actual docs deploys to the website?

No, the opposite.

We don't want to try to install matplotlib on source builds since it's a native extension, and it wouldn't be a good idea to try to build it against a development CPython version.

We don't use the Python build from source to deploy the website, so the missing optional dependency doesn't really matter there. This patch makes the dependency available on our docs deployment job, which is what we really care about.

Ah sorry, the logic is indeed the right way around. I'd tested it locally and wondered why images weren't created, and it's because they're not generated when ogp_image is defined in conf.py.

Anyway, thanks for picking this up, python/docsbuild-scripts#147 had been sitting idle for too long!

We've made python/docsbuild-scripts#242 and #129120 to trial it on 3.14, and we can check the performance and space used is okay.