html theme: Add favicon_url and logo_url

To embed the external favicon and logo image, this adds new template
variable `favicon_url` and `logo_url` that point the external URL or
relative path for the favicon/logo file from current file.  It helps to
use it on template files.

CHANGES

@@ -13,6 +13,7 @@ Incompatible changes
 Deprecated
 ----------
 
+* ``favicon`` and ``logo`` variable in HTML templates
 * The ``follow_wrapped`` argument of ``sphinx.util.inspect.signature()``
 * ``sphinx.ext.autodoc.Documenter.get_object_members()``
 * ``sphinx.ext.autodoc.DataDeclarationDocumenter``

doc/extdev/deprecated.rst

@@ -26,6 +26,16 @@ The following is a list of deprecated interfaces.
      - (will be) Removed
      - Alternatives
 
+   * - ``favicon`` variable in HTML templates
+     - 3.4
+     - TBD
+     - ``favicon_url``
+
+   * - ``logo`` variable in HTML templates
+     - 3.4
+     - TBD
+     - ``logo_url``
+
    * - The ``follow_wrapped`` argument of ``sphinx.util.inspect.signature()``
      - 3.4
      - 5.0

doc/templating.rst

@@ -274,7 +274,19 @@ in the future.
 
 .. data:: favicon
 
-   The path to the HTML favicon in the static path, or ``''``.
+   The path to the HTML favicon in the static path, or URL to the favicon, or
+   ``''``.
+
+   .. deprecated:: 4.0
+
+      Recommend to use ``favicon_url`` instead.
+
+.. data:: favicon_url
+
+   The relative path to the HTML favicon image from the current document, or
+   URL to the favicon, or ``''``.
+
+   .. versionadded:: 4.0
 
 .. data:: file_suffix
 
@@ -297,7 +309,19 @@ in the future.
 
 .. data:: logo
 
-   The path to the HTML logo image in the static path, or ``''``.
+   The path to the HTML logo image in the static path, or URL to the logo, or
+   ``''``.
+
+   .. deprecated:: 4.0
+
+      Recommend to use ``logo_url`` instead.
+
+.. data:: logo_url
+
+   The relative path to the HTML logo image from the current document, or URL
+   to the logo, or ``''``.
+
+   .. versionadded:: 4.0
 
 .. data:: master_doc
 

sphinx/builders/html/__init__.py

@@ -444,8 +444,8 @@ class StandaloneHTMLBuilder(Builder):
         else:
             self.last_updated = None
 
-        logo = self.proc_resource_ref(self.config.html_logo)
-        favicon = self.proc_resource_ref(self.config.html_favicon)
+        logo = path.basename(self.config.html_logo) if self.config.html_logo else ''
+        favicon = path.basename(self.config.html_favicon) if self.config.html_favicon else ''
 
         if not isinstance(self.config.html_use_opensearch, str):
             logger.warning(__('html_use_opensearch config value must now be a string'))
@@ -1147,6 +1147,26 @@ def setup_js_tag_helper(app: Sphinx, pagename: str, templatexname: str,
     context['js_tag'] = js_tag
 
 
+def setup_resource_paths(app: Sphinx, pagename: str, templatename: str,
+                         context: Dict, doctree: Node) -> None:
+    """Set up relative resource paths."""
+    pathto = context.get('pathto')
+
+    # favicon_url
+    favicon = context.get('favicon')
+    if not isurl(favicon):
+        context['favicon_url'] = pathto('_static/' + favicon, resource=True)
+    else:
+        context['favicon_url'] = favicon
+
+    # logo_url
+    logo = context.get('logo')
+    if not isurl(logo):
+        context['logo_url'] = pathto('_static/' + logo, resource=True)
+    else:
+        context['logo_url'] = logo
+
+
 def validate_math_renderer(app: Sphinx) -> None:
     if app.builder.format != 'html':
         return
@@ -1267,6 +1287,7 @@ def setup(app: Sphinx) -> Dict[str, Any]:
     app.connect('config-inited', validate_html_favicon, priority=800)
     app.connect('builder-inited', validate_math_renderer)
     app.connect('html-page-context', setup_js_tag_helper)
+    app.connect('html-page-context', setup_resource_paths)
 
     # load default math renderer
     app.setup_extension('sphinx.ext.mathjax')

sphinx/themes/agogo/layout.html

@@ -13,9 +13,9 @@
 {% block header %}
     <div class="header-wrapper" role="banner">
       <div class="header">
-        {%- if logo %}
+        {%- if logo_url %}
           <p class="logo"><a href="{{ pathto(master_doc)|e }}">
-            <img class="logo" src="{{ pathto(logo, 1)|e }}" alt="Logo"/>
+            <img class="logo" src="{{ logo_url|e }}" alt="Logo"/>
           </a></p>
         {%- endif %}
         {%- block headertitle %}

sphinx/themes/basic/layout.html

@@ -53,9 +53,9 @@
       <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
         <div class="sphinxsidebarwrapper">
           {%- block sidebarlogo %}
-          {%- if logo %}
+          {%- if logo_url %}
             <p class="logo"><a href="{{ pathto(master_doc)|e }}">
-              <img class="logo" src="{{ pathto(logo, 1)|e }}" alt="Logo"/>
+              <img class="logo" src="{{ logo_url|e }}" alt="Logo"/>
             </a></p>
           {%- endif %}
           {%- endblock %}
@@ -140,8 +140,8 @@
           title="{% trans docstitle=docstitle|e %}Search within {{ docstitle }}{% endtrans %}"
           href="{{ pathto('_static/opensearch.xml', 1) }}"/>
     {%- endif %}
-    {%- if favicon %}
-    <link rel="shortcut icon" href="{{ pathto(favicon, 1)|e }}"/>
+    {%- if favicon_url %}
+    <link rel="shortcut icon" href="{{ favicon_url|e }}"/>
     {%- endif %}
     {%- endif %}
 {%- block linktags %}

sphinx/themes/basic/opensearch.xml

@@ -6,8 +6,8 @@
   <Url type="text/html" method="get"
        template="{{ use_opensearch }}/{{ pathto('search') }}?q={searchTerms}"/>
   <LongName>{{ docstitle|e }}</LongName>
-{%- if favicon %}
-  <Image height="16" width="16" type="image/x-icon">{{ use_opensearch }}/{{ pathto(favicon, 1)|e }}</Image>
+{%- if favicon_url %}
+  <Image height="16" width="16" type="image/x-icon">{{ use_opensearch }}/{{ favicon_url|e }}</Image>
 {%- endif %}
 {% block extra %} {# Put e.g. an <Image> element here. #} {% endblock %}
 </OpenSearchDescription>

sphinx/themes/haiku/layout.html

@@ -36,11 +36,11 @@
         {%- block haikuheader %}
         {%- if theme_full_logo != "false" %}
         <a href="{{ pathto('index') }}">
-          <img class="logo" src="{{ pathto(logo, 1)|e }}" alt="Logo"/>
+          <img class="logo" src="{{ logo_url|e }}" alt="Logo"/>
         </a>
         {%- else %}
         {%- if logo -%}
-          <img class="rightlogo" src="{{ pathto(logo, 1)|e }}" alt="Logo"/>
+          <img class="rightlogo" src="{{ logo_url|e }}" alt="Logo"/>
         {%- endif -%}
         <h1 class="heading"><a href="{{ pathto('index') }}">
           <span>{{ shorttitle|e }}</span></a></h1>