Use sphinxext-opengraph to generate OpenGraph metadata

[hugovk]

For python/docs-community#63.

Similar to python/devguide#953 already deployed for the devguide.

Add Open Graph metadata using https://github.com/wpilibsuite/sphinxext-opengraph.

This adds <meta name="description"> and <meta property="og:*"> metadata, such as:

<meta property="og:title" content="What’s New In Python 3.12" />
<meta property="og:type" content="website" />
<meta property="og:url" content="https://hugovk-cpython.readthedocs.io/en/add-og-metadata2/whatsnew/3.12.html" />
<meta property="og:site_name" content="Python documentation" />
<meta property="og:description" content="Release, 3.12.0a2,, Date, December 01, 2022,. This article explains the new features in Python 3.12, compared to 3.11. For full details, see the changelog. Summary – Release highlights: Important d..." />
<meta property="og:image" content="https://hugovk-cpython.readthedocs.io/en/add-og-metadata2/_static/og-image.png" />
<meta property="og:image:alt" content="Python documentation" />
<meta name="description" content="Release, 3.12.0a2,, Date, December 01, 2022,. This article explains the new features in Python 3.12, compared to 3.11. For full details, see the changelog. Summary – Release highlights: Important d..." />
<meta property="og:image:width" content="1200">
<meta property="og:image:height" content="630">

Demo

With another branch, I temporarily changed this so the image link works:

-ogp_site_url = 'https://docs.python.org/3/'
+ogp_site_url = 'https://hugovk-cpython.readthedocs.io/en/add-og-metadata2/'

https://hugovk-cpython.readthedocs.io/en/add-og-metadata2/whatsnew/3.12.html

SEO

Helps SEO by adding <meta name="description">.

SEO measurements using Google's PageSpeed Insights (using main on my RTD vs. my demo on RTD to keep as many hosting variables the same):

Before: 66	After: 81

Notably fixes "Document does not have a meta description".

Sharing

This also improves the previews when sharing on Facebook, Slack, Discord, Twitter, etc.

For example, using the Facebook sharing deebugger:

Before	After

Here's both shared on Slack:

OG image

Like python/devguide#953, generated with https://github.com/hugovk/pixel-tools/blob/1618b2a09bd5998899958856b7fef4503f95cba2/og_image.py using the font from https://github.com/python/pythondotorg/tree/main/static/fonts:

python og_image.py --text CPython --logo tests/python-logo.png --size 210 --font ../pythondotorg/static/fonts/FluxRegular.ttf
...
optipng -o7 -zm1-9 Doc/_static/og-image.png

What text should we have in the image? The PR currently has "CPython", here's a few other options (all font size 210 except the last is 180). For multiple words, I could adjust og_image.py to do multiline text too.

Note

The homepage and download pages do not get metadata, for example:

• https://hugovk-cpython.readthedocs.io/en/add-og-metadata2/index.html
• https://hugovk-cpython.readthedocs.io/en/add-og-metadata2/download.html

I think it's because because they're additional pages added via conf.py like this?

# Additional templates that should be rendered to pages.
html_additional_pages = {
    'download': 'download.html',
    'index': 'indexcontent.html',
}

If these also need it, should they be dealt with separately?

Skip issue or news?

We have python/docs-community#63, should we also have an issue in this repo? And news?

[CAM-Gerlach]

Big picture comments (literally):

• The image is rather big, and takes up a large amount of space in the preview disproportionate (IMO) relative to its value for readers. Can we make it a lot smaller (especially in height), trim off the borders and/or otherwise ensure it is scaled down.
• Of the options listed, I prefer Python Docs, but I imagine the PSF trademarks committee might need to review it if its something other than one of the official logotypes. @malemburg ?
• We should backport it to at least the primary/default version site for this to have proper effect, but can we add the extension in a way that will gracefully fallback if the plugin is not installed (e.g. on downstream redistributors, who are unlikely to need, want or have it)?

[ezio-melotti]

The image is rather big, and takes up a large amount of space in the preview disproportionate (IMO) relative to its value for readers.

IIRC this is the standard/recommended size, but otherwise I agree that it could be smaller.

Of the options listed, I prefer Python Docs

+1

but I imagine the PSF trademarks committee might need to review it if its something other than one of the official logotypes. @malemburg ?

We have already checked with them while working on the Devguide PR and mentioned that we are planning to do the same on related repos, so everything should be already ok on this front.

[hugovk]

Yes, the required minimum is 200 x 200 and recommended minimum is 1200 x 630, with 1.91:1 aspect ratio.

https://developers.facebook.com/docs/sharing/webmasters/images says:

Requirements

• The minimum allowed image dimension is 200 x 200 pixels.
• The size of the image file must not exceed 8 MB.
• Use images that are at least 1200 x 630 pixels for the best display on high resolution devices. At the minimum, you should use images that are 600 x 315 pixels to display link page posts with larger images.
• If your image is smaller than 600 x 315 px, it will still display in the link page post, but the size will be much smaller.
• We've also re-designed link page posts so that the aspect ratio for images is the same across desktop and mobile Feed. Try to keep your images as close to 1.91:1 aspect ratio as possible to display the full image in Feed without any cropping.

As a quick test, autocropping to 1022 x 330:

https://hugovk-cpython.readthedocs.io/en/add-og-metadata2/whatsnew/3.12.html

Gives:

https://developers.facebook.com/tools/debug/?q=https%3A%2F%2Fhugovk-cpython.readthedocs.io%2Fen%2Fadd-og-metadata2%2Fwhatsnew%2F3.12.html

[hugovk]

• We should backport it to at least the primary/default version site for this to have proper effect, but can we add the extension in a way that will gracefully fallback if the plugin is not installed (e.g. on downstream redistributors, who are unlikely to need, want or have it)?

@AA-Turner Do you know if this is possible with Sphinx?

[hugovk]

"Python Docs", single line or multiline?

(Font sizes 160, 210, 230)

[CAM-Gerlach]

Yes, the required minimum is 200 x 200 and recommended minimum is 1200 x 630, with 1.91:1 aspect ratio.

Okay; could you try to output it at 482 x 200 and see if it displays smaller? Or at the recommended minimum size?

@AA-Turner Do you know if this is possible with Sphinx?

conf.py is just a Python script; couldn't you do

try:
    import sphinxext.opengraph
except ImportError:
    pass
else:
    extensions.append("sphinxext.opengraph")

"Python Docs", single line or multiline?

I guess multiline, if its a mixed aspect ratio. If we must use the space, may as well get as much out of it as we can...

[CAM-Gerlach]

I added skip-issue since the issue is on another repo, but left out skip-news since we might want to write a news entry if we're adding a new docs dependency, if an optional one.

[hugovk]

Yes, the required minimum is 200 x 200 and recommended minimum is 1200 x 630, with 1.91:1 aspect ratio.

Okay; could you try to output it at 482 x 200 and see if it displays smaller?

Here's how 482 x 200 looks:

(Note to self: python og_image.py --text "Python Docs" --logo tests/python-logo.png --font ../pythondotorg/static/fonts/FluxRegular.ttf --text "Python Docs" --size 100 -W 482 -H 200 -lw 15 -lh 15)

This is smaller because Facebook says:

If your image is smaller than 600 x 315 px, it will still display in the link page post, but the size will be much smaller.

---

Or at the recommended minimum size?

The recommended minimum 1200 x 630 that we started with. The "absolute" minimum is 200 x 200, it's just the icon and looks like:

(python og_image.py --text "Python Docs" --logo tests/python-logo.png --font ../pythondotorg/static/fonts/FluxRegular.ttf --text "Python Docs" --size 100 -W 200 -H 200 -lw 0 -lh 0)

---

conf.py is just a Python script; couldn't you do

try:
    import sphinxext.opengraph
except ImportError:
    pass
else:
    extensions.append("sphinxext.opengraph")

Ah yes, thanks :)

I guess multiline, if its a mixed aspect ratio. If we must use the space, may as well get as much out of it as we can...

👍

[malemburg]

but I imagine the PSF trademarks committee might need to review it if its something other than one of the official logotypes. @malemburg ?

We have already checked with them while working on the Devguide PR and mentioned that we are planning to do the same on related repos, so everything should be already ok on this front.

Please send in the final version for official approval. The versions I'm seeing on this ticket mostly appear fine. Just please make sure that the logo is not shown cut-off in parts. I know that this is difficult with social media links, but it would be good to at least have the complete logo shown in the previews.

[CAM-Gerlach]

The smaller version takes up a lot less unnecessary space, though it does omit the "Python Docs" nameplate/logotype. Naively to me, the former would seem worth it, but I don't have the same background in the uses of opengraph metadata, beyond anecdotal experience with the displayed previews a handful of common places. What do others think?

[hugovk]

Here's a whole load of demos with various sizes:

• https://hugovk.neocities.org/og-test/200x200.html
• https://hugovk.neocities.org/og-test/315x315.html
• https://hugovk.neocities.org/og-test/400x400.html
• https://hugovk.neocities.org/og-test/450x450.html
• https://hugovk.neocities.org/og-test/482x200.html
• https://hugovk.neocities.org/og-test/500x500.html
• https://hugovk.neocities.org/og-test/599x599.html
• https://hugovk.neocities.org/og-test/600x600.html
• https://hugovk.neocities.org/og-test/1022x330.html
• https://hugovk.neocities.org/og-test/1200x630.html

I think the square logo version without the "Python Docs" text is quite good, we're not showing a big banner photo and it shows more of the relevant text too.

400x400 seems to be the upper bound to still show as a square logo:

Here's 200x200, looks about the same:

In Discord:

In Slack:

So I think 200x200 is a good one to use. I'll update this PR and add a bit of padding too so it's not too close to the border for Facebook.

[hugovk]

Updated to 200x200 logo with 5px padding, demo at https://hugovk-cpython.readthedocs.io/en/add-og-metadata2/whatsnew/3.12.html

[ezio-melotti]

One data point that might be relevant to the discussion is that (at least on Discord) clicking on the image just opens the image -- not the link.

This behavior is useful when sharing cat pics from your favorite social media website, since you mostly care about the pic itself (and you would generally be better off avoiding the comment section). However in our case we don't care about the image itself, and having such a big image will just increases the chances that the user will click that instead of the actual link.

IOW, the 200x200 logo might be a better fit for our use-case.

[CAM-Gerlach]

LGTM, aside from adding relevant links to the NEWS entry. Thanks @hugovk !

[CAM-Gerlach]

One data point that might be relevant to the discussion is that (at least on Discord) clicking on the image just opens the image -- not the link.

Hmm, interesting...I wasn't aware of this behavior, though this tends to imply that either it isn't widespread, or because I as a user have never actually tried to click the image.

[miss-islington]

Thanks @hugovk for the PR 🌮🎉.. I'm working now to backport this PR to: 3.11.
🐍🍒⛏🤖 I'm not a witch! I'm not a witch!

[bedevere-bot]

GH-100115 is a backport of this pull request to the 3.11 branch.

[hugovk]

Backporting to 3.11, so we get it under the default /3/ as well.