Merge pull request #5049 from tk0miya/4193_canonical_url

html: Output ``canonical_url`` metadata if :confval:`html_baseurl` set

CHANGES

@@ -128,6 +128,8 @@ Features added
 * C++, add a ``cpp:texpr`` role as a sibling to ``cpp:expr``.
 * C++, add support for unions.
 * #3606: MathJax should be loaded with async attribute
+* html: Output ``canonical_url`` metadata if :confval:`html_baseurl` set (refs:
+  #4193)
 
 Bugs fixed
 ----------

doc/usage/configuration.rst

@@ -827,6 +827,11 @@ that use Sphinx's HTMLWriter class.
 
    .. versionadded:: 0.4
 
+.. confval:: html_baseurl
+
+   The URL which points to the root of the HTML documentation.  It is used to
+   indicate the location of document like ``canonical_url``.
+
 .. confval:: html_context
 
    A dictionary of values to pass into the template engine's context for all

sphinx/builders/html.py

@@ -1025,6 +1025,12 @@ class StandaloneHTMLBuilder(Builder):
         # part, which relative_uri doesn't really like...
         default_baseuri = default_baseuri.rsplit('#', 1)[0]
 
+        if self.config.html_baseurl:
+            ctx['pageurl'] = posixpath.join(self.config.html_baseurl,
+                                            pagename + self.out_suffix)
+        else:
+            ctx['pageurl'] = None
+
         def pathto(otheruri, resource=False, baseuri=default_baseuri):
             # type: (unicode, bool, unicode) -> unicode
             if resource and '://' in otheruri:
@@ -1578,6 +1584,7 @@ def setup(app):
     app.add_config_value('html_search_scorer', '', None)
     app.add_config_value('html_scaled_image_link', True, 'html')
     app.add_config_value('html_experimental_html5_writer', None, 'html')
+    app.add_config_value('html_baseurl', '', 'html')
 
     # event handlers
     app.connect('config-inited', convert_html_css_files)

sphinx/themes/basic/layout.html

@@ -130,6 +130,9 @@
     {%- block scripts %}
     {{- script() }}
     {%- endblock %}
+    {%- if pageurl %}
+    <link rel="canonical" href="{{ pageurl }}" />
+    {%- endif %}
     {%- if use_opensearch %}
     <link rel="search" type="application/opensearchdescription+xml"
           title="{% trans docstitle=docstitle|e %}Search within {{ docstitle }}{% endtrans %}"

tests/test_build_html.py

@@ -1268,3 +1268,28 @@ def test_html_sidebar(app, status, warning):
 def test_html_manpage(app, cached_etree_parse, fname, expect):
     app.build()
     check_xpath(cached_etree_parse(app.outdir / fname), fname, *expect)
+
+
+@pytest.mark.sphinx('html', testroot='toctree-glob',
+                    confoverrides={'html_baseurl': 'https://example.com/'})
+def test_html_baseurl(app, status, warning):
+    app.build()
+
+    result = (app.outdir / 'index.html').text(encoding='utf8')
+    assert '<link rel="canonical" href="https://example.com/index.html" />' in result
+
+    result = (app.outdir / 'qux' / 'index.html').text(encoding='utf8')
+    assert '<link rel="canonical" href="https://example.com/qux/index.html" />' in result
+
+
+@pytest.mark.sphinx('html', testroot='toctree-glob',
+                    confoverrides={'html_baseurl': 'https://example.com/subdir',
+                                   'html_file_suffix': '.htm'})
+def test_html_baseurl_and_html_file_suffix(app, status, warning):
+    app.build()
+
+    result = (app.outdir / 'index.htm').text(encoding='utf8')
+    assert '<link rel="canonical" href="https://example.com/subdir/index.htm" />' in result
+
+    result = (app.outdir / 'qux' / 'index.htm').text(encoding='utf8')
+    assert '<link rel="canonical" href="https://example.com/subdir/qux/index.htm" />' in result