diff --git a/.hunspell.en.dic b/.hunspell.en.dic index 4ecbd2485..cd0ef5637 100644 --- a/.hunspell.en.dic +++ b/.hunspell.en.dic @@ -1602,3 +1602,6 @@ claude kernel's TOOL1 TOOL2 +sphinxext +opengraph +PNG diff --git a/doc/source/_static/social_preview.png b/doc/source/_static/social_preview.png new file mode 100644 index 000000000..202d030ae Binary files /dev/null and b/doc/source/_static/social_preview.png differ diff --git a/doc/source/conf.py b/doc/source/conf.py index 297902e01..b1f88e366 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -33,6 +33,29 @@ # ones. extensions = [] +# generate Open Graph meta tags so links shared on social media get a +# preview card; extension is an optional dependency, installed on Read The +# Docs through requirements.txt, so skip it when unavailable locally +# find_spec raises an error rather returning None if parent 'sphinxext' +# package is not found +try: + use_ogp = importlib.util.find_spec('sphinxext.opengraph') is not None +except ModuleNotFoundError: + use_ogp = False +if use_ogp: + extensions.append('sphinxext.opengraph') + # on Read The Docs, extension gets site URL of the exact doc version + # built from READTHEDOCS_CANONICAL_URL environment variable; only set a + # fallback URL for builds outside of Read The Docs + if os.environ.get('READTHEDOCS', None) != 'True': + ogp_site_url = 'https://modules.readthedocs.io/en/latest/' + # point to PNG rendering of project logo (relative to site URL) as SVG + # is not supported by social media platforms + ogp_image = '_static/social_preview.png' + ogp_custom_meta_tags = [ + '', + ] + # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] diff --git a/doc/source/requirements.txt b/doc/source/requirements.txt index 3ef203c86..6a5416e87 100644 --- a/doc/source/requirements.txt +++ b/doc/source/requirements.txt @@ -1,2 +1,3 @@ sphinx furo +sphinxext-opengraph