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