def resolve_doctitle(
doctree: nodes.document
) -> Tuple[Optional[nodes.title], Optional[nodes.title]]:
toplevel_sectnode = doctree.next_node(nodes.section)
if not toplevel_sectnode:
return (None, None)
titlenode = _safe_descend(toplevel_sectnode, 0)
# NOTE: nodes.subtitle does not make senses beacuse Sphinx doesn't support
# subtitle:
#
# > Sphinx does not support a "subtitle".
# > Sphinx recognizes it as a mere second level section
#
# ref:
# - https://github.com/sphinx-doc/sphinx/issues/3574#issuecomment-288722585
# - https://github.com/sphinx-doc/sphinx/issues/3567#issuecomment-288093991
if len(toplevel_sectnode) != 2:
return (titlenode, None)
# HACK: For our convenience, we regard second level section title
# (under document) as subtitle::
# <section>
# <title>
# <section>
# <(sub)title>
subtitlenode = toplevel_sectnode[1][0]
if not isinstance(subtitlenode, nodes.title):
return (titlenode, None)
return (titlenode, subtitlenode)
def get_tags(context: Dict[str, Any], doctree: nodes.document,
config: Dict[str, Any]) -> str:
# Set length of description
try:
desc_len = int(config["ogp_description_length"])
except ValueError:
desc_len = DEFAULT_DESCRIPTION_LENGTH
# Get the title and parse any html in it
title = get_title(context["title"], skip_html_tags=False)
title_excluding_html = get_title(context["title"], skip_html_tags=True)
# Parse/walk doctree for metadata (tag/description)
description = get_description(doctree, desc_len,
[title, title_excluding_html])
tags = "\n "
# title tag
tags += make_tag("og:title", title)
# type tag
tags += make_tag("og:type", config["ogp_type"])
# url tag
# Get the URL of the specific page
page_url = urljoin(config["ogp_site_url"],
context["pagename"] + context["file_suffix"])
tags += make_tag("og:url", page_url)
# site name tag
site_name = config["ogp_site_name"]
if site_name:
tags += make_tag("og:site_name", site_name)
# description tag
tags += make_tag("og:description", description)
# image tag
# Get basic values from config
image_url = config["ogp_image"]
ogp_use_first_image = config["ogp_use_first_image"]
ogp_image_alt = config["ogp_image_alt"]
if ogp_use_first_image:
first_image = doctree.next_node(nodes.image)
if (first_image and Path(first_image.get(
"uri", "")).suffix[1:].lower() in IMAGE_MIME_TYPES):
image_url = first_image["uri"]
ogp_image_alt = first_image.get("alt", None)
if image_url:
tags += make_tag("og:image", image_url)
# Add image alt text (either provided by config or from site_name)
if isinstance(ogp_image_alt, str):
tags += make_tag("og:image:alt", ogp_image_alt)
elif ogp_image_alt and site_name:
tags += make_tag("og:image:alt", site_name)
elif ogp_image_alt and title:
tags += make_tag("og:image:alt", title)
# custom tags
tags += "\n".join(config["ogp_custom_meta_tags"])
return tags
def get_tags(
app: Sphinx,
context: Dict[str, Any],
doctree: nodes.document,
config: Dict[str, Any],
) -> str:
# Set length of description
try:
desc_len = int(config["ogp_description_length"])
except ValueError:
desc_len = DEFAULT_DESCRIPTION_LENGTH
# Get the title and parse any html in it
title = get_title(context["title"], skip_html_tags=False)
title_excluding_html = get_title(context["title"], skip_html_tags=True)
# Parse/walk doctree for metadata (tag/description)
description = get_description(doctree, desc_len,
[title, title_excluding_html])
tags = "\n "
# title tag
tags += make_tag("og:title", title)
# type tag
tags += make_tag("og:type", config["ogp_type"])
if os.getenv("READTHEDOCS") and config["ogp_site_url"] is None:
# readthedocs uses html_baseurl for sphinx > 1.8
parse_result = urlparse(config["html_baseurl"])
if config["html_baseurl"] is None:
raise EnvironmentError(
"ReadTheDocs did not provide a valid canonical URL!")
# Grab root url from canonical url
config["ogp_site_url"] = urlunparse((
parse_result.scheme,
parse_result.netloc,
parse_result.path,
"",
"",
"",
))
# url tag
# Get the URL of the specific page
page_url = urljoin(config["ogp_site_url"],
context["pagename"] + context["file_suffix"])
tags += make_tag("og:url", page_url)
# site name tag
site_name = config["ogp_site_name"]
if site_name:
tags += make_tag("og:site_name", site_name)
# description tag
if description:
tags += make_tag("og:description", description)
# image tag
# Get basic values from config
image_url = config["ogp_image"]
ogp_use_first_image = config["ogp_use_first_image"]
ogp_image_alt = config["ogp_image_alt"]
if ogp_use_first_image:
first_image = doctree.next_node(nodes.image)
if (first_image and Path(first_image.get(
"uri", "")).suffix[1:].lower() in IMAGE_MIME_TYPES):
image_url = first_image["uri"]
ogp_image_alt = first_image.get("alt", None)
if image_url:
image_url_parsed = urlparse(image_url)
if not image_url_parsed.scheme:
# Relative image path detected. Make absolute.
image_url = urljoin(config["ogp_site_url"], image_url_parsed.path)
tags += make_tag("og:image", image_url)
# Add image alt text (either provided by config or from site_name)
if isinstance(ogp_image_alt, str):
tags += make_tag("og:image:alt", ogp_image_alt)
elif ogp_image_alt is None and site_name:
tags += make_tag("og:image:alt", site_name)
elif ogp_image_alt is None and title:
tags += make_tag("og:image:alt", title)
# custom tags
tags += "\n".join(config["ogp_custom_meta_tags"])
return tags
