Add site_name Support and Enhance Description (#4)

* Move html tag formatting to a function

* Add support for og:site_name tag

* Enhance description

* Get title by parsing context instead of from doctree

* Add tests to new description creator

* Add newline

* Add newline

Co-authored-by: Dalton Smith <gamefollower26@gmail.com>

Author: TheTripleV

README.md

@@ -12,6 +12,8 @@ These values are placed in the conf.py of your sphinx project.
     * This config option is very important, set it to the URL the site is being hosted on. 
 * `ogp_description_length`
     * Configure the amount of characters taken from a page. The default of 200 is probably good for most people. If something other than a number is used, it defaults back to 200. 
+* `ogp_site_name`
+    * This is not required. Name of the site. This is displayed above the title.
 * `ogp_image`
     * This is not required. Link to image to show.
 * `ogp_type`

sphinxext/opengraph.py

@@ -1,35 +1,182 @@
 from urllib.parse import urljoin
+import docutils.nodes as nodes
+import string
+from html.parser import HTMLParser
+
 
 DEFAULT_DESCRIPTION_LENGTH = 200
 
+class HTMLTextParser(HTMLParser):
+    """
+    Parse HTML into text
+    """
+    def __init__(self):
+        super().__init__()
+        # All text found
+        self.text = ""
+        # Only text outside of html tags
+        self.text_outside_tags = ""
+        self.level = 0
+
+    def handle_starttag(self, tag, attrs):
+        self.level += 1
+        
+    def handle_endtag(self, tag):
+        self.level -= 1
+
+    def handle_data(self, data):
+        self.text += data
+        if self.level == 0:
+            self.text_outside_tags += data
+
+class OGMetadataCreatorVisitor(nodes.NodeVisitor):
+    """
+    Finds the title and creates a description from a doctree
+    """
+
+    def __init__(self, desc_len, known_titles=None, document=None):
+
+        # Hack to prevent requirement for the doctree to be passed in.
+        # It's only used by doctree.walk(...) to print debug messages. 
+        if document == None:
+            class document_cls:
+                class reporter:
+                    @staticmethod
+                    def debug(*args, **kwaargs):
+                        pass
+
+            document = document_cls()
+
+        if known_titles == None:
+            known_titles = []
+
+        super().__init__(document)
+        self.description = ""
+        self.desc_len = desc_len
+        self.list_level = 0
+        self.known_titles = known_titles
+        self.first_title_found = False
+
+        # Exceptions can't be raised from dispatch_departure()
+        # This is used to loop the stop call back to the next dispatch_visit()
+        self.stop = False
+
+    def dispatch_visit(self, node: nodes.Element) -> None:
+
+        if self.stop:
+            raise nodes.StopTraversal
+
+        # Skip all admonitions
+        if isinstance(node, nodes.Admonition):
+            raise nodes.SkipNode
+
+        # Mark start of nested lists
+        if isinstance(node, nodes.Sequential):
+            self.list_level += 1
+            if self.list_level > 1:
+                self.description += "-"
+
+        # Skip the first title if it's the title of the page
+        if not self.first_title_found and isinstance(node, nodes.title):
+            self.first_title_found = True
+            if node.astext() in self.known_titles:
+                raise nodes.SkipNode
+
+        # Only include leaf nodes in the description
+        if len(node.children) == 0:
+            text = node.astext().replace("\r", "").replace("\n", " ").strip()
+
+            # Remove double spaces
+            while text.find("  ") != -1:
+                text = text.replace("  ", " ")
+
+            # Put a space between elements if one does not already exist.
+            if (
+                len(self.description) > 0
+                and len(text) > 0
+                and self.description[-1] not in string.whitespace
+                and text[0] not in string.whitespace + string.punctuation
+            ):
+                self.description += " "
+
+            self.description += text
+
+    def dispatch_departure(self, node: nodes.Element) -> None:
+
+        # Separate title from text
+        if isinstance(node, nodes.title):
+            self.description += ":"
+
+        # Separate list elements
+        if isinstance(node, nodes.Part):
+            self.description += ","
+
+        # Separate end of list from text
+        if isinstance(node, nodes.Sequential):
+            if self.description[-1] == ",":
+                self.description = self.description[:-1]
+            self.description += "."
+            self.list_level -= 1
 
-def get_tags(context, doctree, config):
-    # Get the URL of the specific page
-    page_url = urljoin(config["ogp_site_url"], context["pagename"] + context["file_suffix"])
-    # Get the image from the config
-    image_url = config["ogp_image"]
+        # Check for length
+        if len(self.description) > self.desc_len:
+            self.description = self.description[: self.desc_len]
+            if self.desc_len >= 3:
+                self.description = self.description[:-3] + "..."
 
-    # Get the first X letters from the page (Configured in config)
-    description = doctree.astext().replace('\n', ' ')
+            self.stop = True
+
+
+def make_tag(property: str, content: str) -> str:
+    return f'<meta property="{property}" content="{content}" />\n  '
+
+
+def get_tags(context, doctree, config):
 
+    # Set length of description
     try:
         desc_len = int(config["ogp_description_length"])
     except ValueError:
         desc_len = DEFAULT_DESCRIPTION_LENGTH
 
-    if len(description) > desc_len:
-        description = description[:desc_len - 3] + "..."
+    # Get the title and parse any html in it
+    htp = HTMLTextParser()
+    htp.feed(context["title"])
+    htp.close()
 
-    # Make the ogp tags
-    tags = """
-    <meta property="og:title" content="{title}" />
-    <meta property="og:type" content="{type}" />
-    <meta property="og:url" content="{url}" />
-    <meta property="og:description" content="{desc}" />
-    """.format(title=context["title"], type=config["ogp_type"], url=page_url, desc=description)
+    # Parse/walk doctree for metadata (tag/description)
+    mcv = OGMetadataCreatorVisitor(desc_len, [htp.text, htp.text_outside_tags])
+    doctree.walkabout(mcv)
 
+    tags = "\n  "
+
+    # title tag
+    tags += make_tag("og:title", htp.text)
+
+    # 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", mcv.description)
+
+    # image tag
+    # Get the image from the config
+    image_url = config["ogp_image"]
     if image_url:
-        tags += '<meta property="og:image" content="{image}" />'.format(image=image_url)
+        tags += make_tag("og:image", image_url)
 
     return tags
 
@@ -44,6 +191,7 @@ def setup(app):
     app.add_config_value("ogp_description_length", DEFAULT_DESCRIPTION_LENGTH, "html")
     app.add_config_value("ogp_image", None, "html")
     app.add_config_value("ogp_type", "website", "html")
+    app.add_config_value("ogp_site_name", None, "html")
 
     app.connect('html-page-context', html_page_context)
 

tests/roots/test-double-spacing/conf.py

@@ -0,0 +1,8 @@
+extensions = ["sphinxext.opengraph"]
+
+master_doc = "index"
+exclude_patterns = ["_build"]
+
+html_theme = "basic"
+
+ogp_site_url = "http://example.org/"

tests/roots/test-double-spacing/index.rst

@@ -0,0 +1 @@
+Example sentence 1.  Example sentence 2.

tests/roots/test-list/conf.py

@@ -0,0 +1,8 @@
+extensions = ["sphinxext.opengraph"]
+
+master_doc = "index"
+exclude_patterns = ["_build"]
+
+html_theme = "basic"
+
+ogp_site_url = "http://example.org/"

tests/roots/test-list/index.rst

@@ -0,0 +1,4 @@
+* Item 1
+* Item 2
+* Item 3
+* Item 4

tests/roots/test-nested-lists/conf.py

@@ -0,0 +1,8 @@
+extensions = ["sphinxext.opengraph"]
+
+master_doc = "index"
+exclude_patterns = ["_build"]
+
+html_theme = "basic"
+
+ogp_site_url = "http://example.org/"

tests/roots/test-nested-lists/index.rst

@@ -0,0 +1,8 @@
+* Item 1
+* Item 2
+
+    * Nested Item 1
+    * Nested Item 2
+    
+* Item 3
+* Item 4

tests/roots/test-sitename/conf.py

@@ -0,0 +1,9 @@
+extensions = ["sphinxext.opengraph"]
+
+master_doc = "index"
+exclude_patterns = ["_build"]
+
+html_theme = "basic"
+
+ogp_site_url = "http://example.org/"
+ogp_site_name = "Example's Docs!"

tests/roots/test-sitename/index.rst

@@ -0,0 +1 @@
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse at lorem ornare, fringilla massa nec, venenatis mi. Donec erat sapien, tincidunt nec rhoncus nec, scelerisque id diam. Orci varius natoque penatibus et magnis dis parturient mauris.