8000 Use sphinxext-opengraph to generate OpenGraph metadata by hugovk · Pull Request #953 · python/devguide · GitHub
[go: up one dir, main page]
Skip to content

Use sphinxext-opengraph to generate OpenGraph metadata #953

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.

Sign up for GitHub

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

Merged
merged 13 commits into from
Nov 30, 2022
Merged

Use sphinxext-opengraph to generate OpenGraph metadata #953

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
508bd4c
Use sphinxext-opengraph to generate OpenGraph metadata
hugovk Oct 4, 2022
9f323a9
Merge branch 'main' into add-og-metadata
hugovk Oct 6, 2022
659a6c3
Merge branch 'main' into add-og-metadata
ezio-melotti Oct 7, 2022
3a4f655
Merge branch 'main' into add-og-metadata
ezio-melotti Oct 7, 2022
7e8173d
Merge branch 'main' into add-og-metadata
hugovk Oct 10, 2022
b919f6c
Create logo+text PNG for og:image, SVG not supported
hugovk Oct 10, 2022
d186e52
Include og:image:width and height to ensure shares of new URLs includ…
hugovk Oct 10, 2022
3b2e688
Include og:site_name, displayed for the overall site
hugovk Oct 10, 2022
5b048ea
Use relative path for ogp_image
hugovk Oct 11, 2022
edd71a7
Use sphinxext-opengraph 0.7.1+ to use meta og:description as meta des…
hugovk Nov 2, 2022
d3c69f7
Merge branch 'main' into add-og-metadata
hugovk Nov 2, 2022
684dff2
Add theme colour using Python blue
hugovk Nov 4, 2022
e47cc4f
Regenerate OG image with Flux Regular
hugovk Nov 28, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Next Next commit
Use sphinxext-opengraph to generate OpenGraph metadata
  • Loading branch information
@hugovk
hugovk committed Oct 4, 2022
commit 508bd4c2ac29e6da90775ff168580c42bf334971
5 changes: 5 additions & 0 deletions conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@
'sphinx.ext.intersphinx',
'sphinx.ext.todo',
'sphinx_copybutton',
'sphinxext.opengraph',
'sphinxext.rediraffe',
]

Expand Down Expand Up @@ -97,3 +98,7 @@
}

todo_include_todos = True

# sphinxext-opengraph config
ogp_site_url = "https://devguide.python.org/"
ogp_image = "https://devguide.python.org/_static/python-logo.svg"
Copy link
Member
@ezio-melotti ezio-melotti Oct 6, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Apparently SVGs are not supported, so we should use a different image.

Should we also add more variables?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Will find another image. The recommended image size is 1200 x 630, should we use a Python logo or something else?

I don't think we need any of the other variables.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Re: other variables:

I'll check ogp_custom_meta_tags for <meta name="description">.

python/docs-community#65 (comment)

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'll check ogp_custom_meta_tags for <meta name="description">.

We can use ogp_custom_meta_tags to add it, but it would be hardcoded and we'd like to generate it from each page.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The recommended image size is 1200 x 630, should we use a Python logo or something else?

Since the image is rectangular (and somewhat big), it would be nice if it had both the Python logo and the text "Devguide". If/when we do the same for cpython (or for the peps repo), we can have the same logo but different texts, so that the links are easily distinguishable.

This however would require creating new images, so if you don't want to do that, just a simple logo will do (we can always update the image later).

I don't think we need any of the other variables.

ok

We can use ogp_custom_meta_tags to add it, but it would be hardcoded and we'd like to generate it from each page.

Right, it would be better if the description was created dynamically.

Copy link
Member Author
@hugovk hugovk Oct 10, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

SVG replaced with a PNG of the Python logo + "Devguide".

og-image

I wrote a script to create it (hugovk/pixel-tools#15), so we can re-use that for other repos if we want.

I also squashed out the extra bytes from the PNG using optipng -o7 -zm1-9 _static/og-image.png (57,118 -> 9,573 bytes, 16.76% decrease).

When temporarily setting ogp_image = "https://cpython-devguide--953.org.readthedocs.build/_static/og-image.png" Facebook's sharing debugger shows the following OG metadata/preview:

image

https://developers.facebook.com/tools/debug/?q=https%3A%2F%2Fcpython-devguide--953.org.readthedocs.build%2F

Also included og:image:width and og:image:height because the debugger said "Using these tags will specify the image to the crawler so that it can render it immediately without having to asynchronously".

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The new image looks good -- I wonder if we can use the same font used with the logo though.

https://www.python.org/community/logos/ says

The font used in the logo is called "Flux Regular". The PSF owns a copy but we cannot distribute it, except for work on the PSF's behalf.

Further down on the same page it says:

In general, we want the logo to be used as widely as possible to indicate use of Python or suitability for Python. However, please ask first when using a derived version of the logo or when in doubt.

So we should ask there first, and if they agree we can regenerate the logos with the right font.

This is not a blocker by any means though, so we can merge with the current image and recreate it later.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's taking a while to get the font. It would be nice to get this merged to see how it works when live. Shall we merge this as-is, or with the image removed?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's merge it.
I'll ping Deb again about the font and we can update that in a follow-up PR.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(Continued in main thread: #953 (comment))

1 change: 1 addition & 0 deletions requirements.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,4 +2,5 @@ Sphinx==5.2.1
furo>=2022.6.4
sphinx_copybutton>=0.3.3
sphinx-lint<1
sphinxext-opengraph
sphinxext-rediraffe
0