10000 Added OpenGraph information to the documentation configuration by Mr-Sunglasses · Pull Request #3034 · urllib3/urllib3 · GitHub
[go: up one dir, main page]

Skip to content

Added OpenGraph information to the documentation configuration #3034

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

Merged
merged 4 commits into from
May 19, 2023

Conversation

Mr-Sunglasses
Copy link
Contributor

Fix #1983 Added the OpenGraph information metadata to the documentation configuration so that it looks nice when shared on the platforms supporting The Open Graph protocol.

@sethmlarson
Copy link
Member

@Mr-Sunglasses Thanks for this! It looks like the docs build is failing though, can you take a look?

@Mr-Sunglasses
Copy link
Contributor Author

I have Updated the requirements.txt Now It'll work fine.

@pquentin pquentin added the Skip Changelog Pull requests that don't require a changelog entry label May 19, 2023
@sethmlarson sethmlarson merged commit 4e9060b into urllib3:main May 19, 2023
ogp_title = "urllib3 documentation"
ogp_site_url = "https://urllib3.readthedocs.io"
ogp_type = "website"
ogp_image = "https://github.com/urllib3/urllib3/raw/main/docs/_static/banner_github.svg"
Copy link
Contributor

Choose a reason for hiding this comment

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

OpenGraph does not support SVG, use a PNG instead:

https://stackoverflow.com/a/26876671/724176

Compare python-pillow/Pillow#5498

Copy link
Member

Choose a reason for hiding this comment

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

8000

I found that with the following change, it generates social cards for every page

diff --git a/docs/conf.py b/docs/conf.py
index 69f5c4dd..a2a93fdb 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -42,7 +42,7 @@ extensions = [
 ogp_title = "urllib3 documentation"
 ogp_site_url = "https://urllib3.readthedocs.io"
 ogp_type = "website"
-ogp_image = "https://github.com/urllib3/urllib3/raw/main/docs/_static/banner_github.svg"
+ogp_social_cards = {"image": "images/logo.png", "line_color": "#F09837"}
 ogp_description = "urllib3 is a user-friendly HTTP client library for Python."
 
 # Test code blocks only when explicitly specified

@sethmlarson @pquentin what do you this about using them instead of a static image?

FYI, the little icon is Sphinx's

Copy link
Member

Choose a reason for hiding this comment

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

Sounds good to me, the logo is enough here, urllib3 is already mentioned multiple times.

]

# Open Graph metadata
ogp_title = "urllib3 documentation"
ogp_site_url = "https://urllib3.readthedocs.io"
Copy link
Contributor

Choose a reason for hiding this comment

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

For some reason, the Facebook sharing debugger gets 404s for /latest URLs:
https://urllib3.readthedocs.io/en/latest/advanced-usage.html

https://developers.facebook.com/tools/debug/?q=https%3A%2F%2Furllib3.readthedocs.io%2Fen%2Flatest%2Fadvanced-usage.html

I wonder if it's this line causing mixup with the canonical link.

We don't use it for Pillow (see above) and https://github.com/wpilibsuite/sphinxext-opengraph#options says:

Users hosting documentation on Read The Docs do not need to set any of the following unless custom configuration is wanted.

@hugovk
Copy link
Contributor
hugovk commented May 20, 2023

@Mr-Sunglasses
Copy link
Contributor Author

@hugovk will fix it as soon as possible 😊

@illia-v illia-v mentioned this pull request May 30, 2023
12 tasks
@sethmlarson
Copy link
Member

@Mr-Sunglasses Were you still up for fixing these issues? Otherwise someone else may tackle them in the next few days to get a release out.

@Mr-Sunglasses
Copy link
Contributor Author

@sethmlarson Will fix it by today 👍🏻

@illia-v
Copy link
Member
illia-v commented Jun 7, 2023

I can see we refer to a READTHEDOCS env variable in the config file. I am not sure if it's available at the needed time, but there is READTHEDOCS_CANONICAL_URL too which may be used as ogp_site_url = os.getenv("READTHEDOCS_CANONICAL_URL").

@hugovk
Copy link
Contributor
hugovk commented Jun 7, 2023

We can omit ogp_site_url entirely for RtD: https://github.com/wpilibsuite/sphinxext-opengraph#options

@illia-v
Copy link
Member
illia-v commented Jun 7, 2023

We can omit ogp_site_url entirely for RtD: https://github.com/wpilibsuite/sphinxext-opengraph#options

This is nice, thanks for the info!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Skip Changelog Pull requests that don't require a changelog entry
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Add OpenGraph information to our documentation
5 participants
0