Use canonical URLs when ogp_site_url is not configured

README.md

@@ -13,18 +13,22 @@ Just add `sphinxext.opengraph` to your extensions list in your `conf.py`
 
 ```python
 extensions = [
-   "sphinxext.opengraph",
+    "sphinxext.opengraph",
 ]
 ```
 ## Options
 These values are placed in the conf.py of your sphinx project.
 
-Users hosting documentation on Read The Docs *do not* need to set any of the following unless custom configuration is wanted. The extension will automatically retrieve your site url.
+Users hosting documentation on Read The Docs *do not* need to set any of the following unless custom configuration is wanted. RTD will automatically set`html_baseurl`.
+
+* `html_baseurl`
+    * Configure the canonical url in Sphinx, this is required unless `ogp_site_url` is provided. It should be set to the canonical URL the site is being hosted on.
+
 
 * `ogp_site_url`
-    * This config option is very important, set it to the URL the site is being hosted on. 
+    * Overrides `html_baseurl` for this extension, not required. If set should be the canonical 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. 
+    * 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`
@@ -37,7 +41,7 @@ Users hosting documentation on Read The Docs *do not* need to set any of the fol
     * This sets the ogp type attribute, for more information on the types available please take a look at https://ogp.me/#types. By default it is set to `website`, which should be fine for most use cases.
 * `ogp_custom_meta_tags`
     * This is not required. List of custom html snippets to insert.
-    
+
 ## Example Config
 
 ### Simple Config
@@ -70,17 +74,17 @@ Make sure you place the fields at the very start of the document such that Sphin
 These are some overrides that can be used, you can actually override any tag and field lists will always take priority.
 
 * `:og_description_length:`
-  * Configure the amount of characters to grab for the description of the page. If the value isn't a number it will fall back to `ogp_description_length`. Note the slightly different syntax because this isn't directly an OpenGraph tag.
+    * Configure the amount of characters to grab for the description of the page. If the value isn't a number it will fall back to `ogp_description_length`. Note the slightly different syntax because this isn't directly an OpenGraph tag.
 * `:og:description:`
-  * Lets you override the description of the page.
+    * Lets you override the description of the page.
 * `:og:title:`
-  * Lets you override the title of the page.
+    * Lets you override the title of the page.
 * `:og:type:`
-  * Override the type of the page, for the list of available types take a look at https://ogp.me/#types.
+    * Override the type of the page, for the list of available types take a look at https://ogp.me/#types.
 * `:ogp:image:`
-  * Set the image for the page.[^1]
+    * Set the image for the page.[^1]
 * `:ogp:image:alt:`
-  * Sets the alt text. Will be ignored if there is no image set.
+    * Sets the alt text. Will be ignored if there is no image set.
 
 ### Example
 Remember that the fields **must** be placed at the very start of the file. You can verify Sphinx has picked up the fields if they aren't shown in the final html file.

sphinxext/opengraph/__init__.py

@@ -4,12 +4,16 @@
 
 import docutils.nodes as nodes
 from sphinx.application import Sphinx
+from sphinx.errors import ConfigError
+from sphinx.util import logging
 
 from .descriptionparser import get_description
 from .titleparser import get_title
 
 import os
 
+logger = logging.getLogger(__name__)
+
 
 DEFAULT_DESCRIPTION_LENGTH = 200
 
@@ -67,26 +71,17 @@ def get_tags(
     # type tag
     tags["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"])
-
+    # url tag
+    # Get the canonical URL if ogp_site_url is not configured
+    if config["ogp_site_url"] is None:
+        # either ogp_site_url or html_baseurl should be configured
         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,
-                "",
-                "",
-                "",
+            logger.info(
+                "sphinxext-opengrpah: A URL has not been configured and is required as per the OpenGraph Specification. Can be ignored if deploying in RTD environments."
             )
-        )
 
-    # url tag
+        config["ogp_site_url"] = config["html_baseurl"]
+
     # Get the URL of the specific page
     if context["builder"] == "dirhtml":
         page_url = urljoin(config["ogp_site_url"], context["pagename"] + "/")

tests/roots/test-arbitrary-tags/conf.py

@@ -5,4 +5,4 @@
 
 html_theme = "basic"
 
-ogp_site_url = "http://example.org/en/latest/"
+html_baseurl = "http://example.org/en/latest/"

tests/roots/test-custom-tags/conf.py

@@ -5,7 +5,7 @@
 
 html_theme = "basic"
 
-ogp_site_url = "http://example.org/en/latest/"
+html_baseurl = "http://example.org/en/latest/"
 
 ogp_custom_meta_tags = [
     '<meta property="og:ignore_canonical" content="true" />',

tests/roots/test-description-length/conf.py

@@ -5,5 +5,5 @@
 
 html_theme = "basic"
 
-ogp_site_url = "http://example.org/en/latest/"
+html_baseurl = "http://example.org/en/latest/"
 ogp_description_length = 50

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

@@ -5,4 +5,4 @@
 
 html_theme = "basic"
 
-ogp_site_url = "http://example.org/en/latest/"
+html_baseurl = "http://example.org/en/latest/"

tests/roots/test-first-image-no-image/conf.py

@@ -6,7 +6,7 @@
 html_theme = "basic"
 
 ogp_site_name = "Example's Docs!"
-ogp_site_url = "http://example.org/en/latest/"
+html_baseurl = "http://example.org/en/latest/"
 ogp_image = "http://example.org/en/latest/image33.png"
 ogp_image_alt = "TEST"
 ogp_use_first_image = True

tests/roots/test-first-image/conf.py

@@ -6,7 +6,7 @@
 html_theme = "basic"
 
 ogp_site_name = "Example's Docs!"
-ogp_site_url = "http://example.org/en/latest/"
+html_baseurl = "http://example.org/en/latest/"
 ogp_image = "http://example.org/en/latest/image33.png"
 ogp_image_alt = "TEST"
 ogp_use_first_image = True

tests/roots/test-image-rel-paths/conf.py

@@ -6,5 +6,5 @@
 html_theme = "basic"
 
 ogp_site_name = "Example's Docs!"
-ogp_site_url = "http://example.org/en/latest/"
+html_baseurl = "http://example.org/en/latest/"
 ogp_use_first_image = True

tests/roots/test-image/conf.py

@@ -6,5 +6,5 @@
 html_theme = "basic"
 
 ogp_site_name = "Example's Docs!"
-ogp_site_url = "http://example.org/en/latest/"
+html_baseurl = "http://example.org/en/latest/"
 ogp_image = "http://example.org/en/latest/image.png"

tests/roots/test-list/conf.py

@@ -5,4 +5,4 @@
 
 html_theme = "basic"
 
-ogp_site_url = "http://example.org/en/latest/"
+html_baseurl = "http://example.org/en/latest/"

tests/roots/test-local-image/conf.py

@@ -6,5 +6,5 @@
 html_theme = "basic"
 
 ogp_site_name = "Example's Docs!"
-ogp_site_url = "http://example.org/en/latest/"
+html_baseurl = "http://example.org/en/latest/"
 ogp_image = "_static/sample.jpg"

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

@@ -5,4 +5,4 @@
 
 html_theme = "basic"
 
-ogp_site_url = "http://example.org/en/latest/"
+html_baseurl = "http://example.org/en/latest/"

tests/roots/test-rtd-default/conf.py → tests/roots/test-override-url/conf.py

@@ -4,3 +4,6 @@
 exclude_patterns = ["_build"]
 
 html_theme = "basic"
+
+html_baseurl = "http://example.org/en/latest/"
+ogp_site_url = "https://example.com/en/stable/"

tests/roots/test-override-url/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.

tests/roots/test-overrides-complex/conf.py

@@ -6,5 +6,5 @@
 html_theme = "basic"
 
 ogp_site_name = "Example's Docs!"
-ogp_site_url = "http://example.org/en/latest/"
+html_baseurl = "http://example.org/en/latest/"
 ogp_image_alt = "Example Alt Text"

tests/roots/test-overrides-simple/conf.py

@@ -6,6 +6,6 @@
 html_theme = "basic"
 
 ogp_site_name = "Example's Docs!"
-ogp_site_url = "http://example.org/en/latest/"
+html_baseurl = "http://example.org/en/latest/"
 ogp_image = "http://example.org/en/latest/image.png"
 ogp_type = "book"

tests/roots/test-quotation-marks/conf.py

@@ -7,4 +7,4 @@
 
 smartquotes = False
 
-ogp_site_url = "http://example.org/en/latest/"
+html_baseurl = "http://example.org/en/latest/"

tests/roots/test-simple/conf.py

@@ -5,4 +5,4 @@
 
 html_theme = "basic"
 
-ogp_site_url = "http://example.org/en/latest/"
+html_baseurl = "http://example.org/en/latest/"

tests/roots/test-sitename/conf.py

@@ -5,5 +5,5 @@
 
 html_theme = "basic"
 
-ogp_site_url = "http://example.org/en/latest/"
+html_baseurl = "http://example.org/en/latest/"
 ogp_site_name = "Example's Docs!"

tests/roots/test-skip-admonitions/conf.py

@@ -5,4 +5,4 @@
 
 html_theme = "basic"
 
-ogp_site_url = "http://example.org/en/latest/"
+html_baseurl = "http://example.org/en/latest/"

tests/roots/test-skip-code-block/conf.py

@@ -5,5 +5,5 @@
 
 html_theme = "basic"
 
-ogp_site_url = "http://example.org/en/latest/"
+html_baseurl = "http://example.org/en/latest/"
 ogp_description_length = 100

tests/roots/test-skip-comments/conf.py

@@ -5,4 +5,4 @@
 
 html_theme = "basic"
 
-ogp_site_url = "http://example.org/en/latest/"
+html_baseurl = "http://example.org/en/latest/"

tests/roots/test-skip-raw/conf.py

@@ -5,5 +5,5 @@
 
 html_theme = "basic"
 
-ogp_site_url = "http://example.org/en/latest/"
+html_baseurl = "http://example.org/en/latest/"
 ogp_description_length = 100

tests/roots/test-skip-title/conf.py

@@ -5,4 +5,4 @@
 
 html_theme = "basic"
 
-ogp_site_url = "http://example.org/en/latest/"
+html_baseurl = "http://example.org/en/latest/"

tests/roots/test-type/conf.py

@@ -5,5 +5,5 @@
 
 html_theme = "basic"
 
-ogp_site_url = "http://example.org/en/latest/"
+html_baseurl = "http://example.org/en/latest/"
 ogp_type = "article"

tests/test_options.py

@@ -40,6 +40,14 @@ def test_dirhtml_url(og_meta_tags):
     assert get_tag_content(og_meta_tags, "url") == "http://example.org/en/latest/index/"
 
 
+@pytest.mark.sphinx("html", testroot="override-url")
+def test_override_url(og_meta_tags):
+    assert (
+        get_tag_content(og_meta_tags, "url")
+        == "https://example.com/en/stable/index.html"
+    )
+
+
 @pytest.mark.sphinx("html", testroot="image")
 def test_image(og_meta_tags):
     assert (
@@ -215,36 +223,3 @@ def test_arbitrary_tags(og_meta_tags):
         == "http://example.org/en/latest/video.mp4"
     )
     assert get_tag_content(og_meta_tags, "video:type") == "video/mp4"
-
-
-# use same as simple, as configuration is identical to overriden
-@pytest.mark.sphinx("html", testroot="simple")
-def test_rtd_override(app: Sphinx, monkeypatch):
-    monkeypatch.setenv("READTHEDOCS", "True")
-    app.config.html_baseurl = "https://failure.com/en/latest/"
-
-    app.build()
-    tags = conftest._og_meta_tags(app)
-
-    assert get_tag_content(tags, "url") == "http://example.org/en/latest/index.html"
-
-
-@pytest.mark.sphinx("html", testroot="rtd-default")
-def test_rtd_valid(app: Sphinx, monkeypatch):
-    monkeypatch.setenv("READTHEDOCS", "True")
-    app.config.html_baseurl = "https://failure.com/en/latest/"
-
-    app.build()
-    tags = conftest._og_meta_tags(app)
-
-    assert get_tag_content(tags, "url") == "https://failure.com/en/latest/index.html"
-
-
-# use rtd-default, as we are not changing configuration, but RTD variables
-@pytest.mark.sphinx("html", testroot="rtd-invalid")
-def test_rtd_invalid(app: Sphinx, monkeypatch):
-    monkeypatch.setenv("READTHEDOCS", "True")
-    app.config.html_baseurl = None
-
-    with pytest.raises(Exception):
-        app.build()