Add block to allow override of logo and logo link

[peterjc]

Problem

Referring to the theme configuration documentation, https://sphinx-rtd-theme.readthedocs.io/en/stable/configuring.html in my conf.py I am using something like this:

html_theme_options = {
    'logo_only': True,
    # ...
}
html_logo = "../images/logo.svg"

Results

My sidebar now has the logo at the top (without the house icon and project name as well, which was the default). So far so good.

Expected Results

I don't want them to link to the documentation master page, but rather the project's home page, e.g. not www.example.org/doc/index.html but www.example.org instead.

Looking at the source code, the theme is currently hard coded to have the top of the side bar home icon and/or logo image to be a link to the documentation,

https://github.com/readthedocs/sphinx_rtd_theme/blob/0.4.3/sphinx_rtd_theme/layout.html#L114

          {% if logo and theme_logo_only %}
            <a href="{{ pathto(master_doc) }}">
          {% else %}
            <a href="{{ pathto(master_doc) }}" class="icon icon-home"> {{ project }}
          {% endif %}

I would like to have another setting logo_url (as used in logilab-sphinx-theme), or similar (e.g. projectlink as used in guzzle_sphinx_theme).

Simplistically (if applied to both the home icon + project name and logo), it might be implemented something like this:

          {% if logo and theme_logo_only %}
            {% if logo_url %}
              <a href="{{ logo_url }}">
            {% else %}
              <a href="{{ pathto(master_doc) }}">
            {% endif %}
          {% else %}
            {% if logo_url %}
              <a href="{{ logo_url }}" class="icon icon-home"> {{ project }}
            {% else %}
              <a href="{{ pathto(master_doc) }}" class="icon icon-home"> {{ project }}
            {% endif %}
          {% endif %}

Environment Info

• Python Version: 3.6
• Sphinx Version: 2.1.2
• RTD Theme Version: 0.4.3

[Blendify]

I don't think we should add another configuration option here. Instead, we could add a block so you can easily override this using templates.

[peterjc]

That would work for me, I think,

[agjohnson]

I agree, this doesn't make for a good theme option. We'd accept a PR for a granular block, but it's not a high priority for core team here. You can also override the sidebartitle block on your own _templates path and customize this on your own without a theme change.

We've wanted to add more configurable blocks, but I don't know when this will happen.

[nevetS]

A solution until #978 is merged for is to change the link using a javascript include. This works for the version of the rtd_theme that I currently am working with. (sphnx_rtd_theme version 0.5.0) It may or may not work with other versions, but customizing it for changes should be pretty straight forward. It simply finds the html elements with links that I wanted to change and changes them.

in conf.py

html_js_files = [
    'my_custom.js',
]

in _static/my_custom.js

// this function changes a relative URL into an absolute url
// from https://stackoverflow.com/questions/14780350/convert-relative-path-to-absolute-using-javascript
function absolute_url(base, relative) {
    var stack = base.split("/"),
        parts = relative.split("/");
    stack.pop(); // remove current file name (or empty string)
                 // (omit if "base" is the current folder without trailing slash)
    for (var i=0; i<parts.length; i++) {
        if (parts[i] == ".")
            continue;
        if (parts[i] == "..")
            stack.pop();
        else
            stack.push(parts[i]);
    }
    return stack.join("/");
}

//This function is called when the page is fully loaded
// it changes the URLs on the logo and on the breadcrumb home icon
$(document).ready(function(){
    // make the breadcrumb home icon link point to a relative path one directory up from the home page
    var my_custom_icon_url=absolute_url(window.location.href,document.getElementById("documentation_options").getAttribute("data-url_root")+'../');
    // make the logo url point to an external page
    var my_custom_logo_url="http://link.for.logo/";
    var home_elements = $('.icon-home');
    var logo_element = home_elements[0];
    var breadcrumb_home_element = home_elements[1];
    breadcrumb_home_element.href=my_custom_icon_url;
    logo_element.href=my_custom_logo_url;
});

[Blendify]

This will be supported natively in sphinx 4.0 see sphinx-doc/sphinx#8737

I do not think we need a block just for the logo given the feature to use a URL will be supported directly from sphinx.

Note, you can always override sidebartitle for full customization.

[peterjc]

I think sphinx-doc/sphinx#8737 is about specifying the logo image source as a URL, not setting the URL you want the image to link to when clicked on.

[edited to fix link as in a different repo]