Documentation: favicon and logo variables not documented properly with 6.0.0 release

[ViktorHaag]

Describe the bug

The Deprecated APIs documentation page still lists the removal of favico and logo variables in HTML templates as "TBD". However, they appear to have been removed for the 6.0.0 release as of PR #10562.

How to Reproduce

Build docs with a template that has a conditional inclusion of the form:

        {%- if logo -%}
        . . .
        {%- endif -%}

With 5.3.0 this would still include the content in HTML output; with 6.0.0, the content is no longer included.

Switching the conditional inclusion to {%- if logo_url -%} with 6.0.0 makes the build correctly include the content in the output again.

Environment Information

text Platform: darwin; (macOS-13.1-x86_64-i386-64bit) Python version: 3.11.1 (main, Dec 8 2022, 10:20:55) [Clang 14.0.0 (clang-1400.0.29.202)]) Python implementation: CPython Sphinx version: 6.0.0 Docutils version: 0.19 Jinja2 version: 3.1.2

Sphinx extensions

No response

Additional context

Deprecated APIs page needs an update to note that now logo and favicon have been removed in favour of logo_url and favicon_url as of 6.0.0.

[choldgraf]

Is there any chance we can go through a deprecation cycle for this? It would be helpful if there were a check for html_logo and html_favicon and throw a warning rather than just error in the HTML template.

[AA-Turner]

Is there any chance we can go through a deprecation cycle for this? It would be helpful if there were a check for html_logo and html_favicon and throw a warning rather than just error in the HTML template.

Hi Chris, this was deprecated in Sphinx 4 (#8737) and removed in Sphinx 6 -- this is the standard 2 release deprecation period for Sphinx. The fix is simply to rename logo to logo_url and favicon to favicon_url.

A

[choldgraf]

Huh - I never noticed a warning in any of my builds. Maybe i just missed it.

I am also a bit confused - it's called logo_url but in my experience most people use a direct path instead of a URL. Is only a URL allowed now?

Edit: note to self / others: looks from the docs that the functionality is the exact same, just had URL in the variable name now

[AA-Turner]

I am also a bit confused - it's called logo_url but in my experience most people use a direct path instead of a URL. Is only a URL allowed now?

Edit: note to self / others: looks from the docs that the functionality is the exact same, just had URL in the variable name now

The better name perhaps would've been logo_path or logo_uri, but the change was to allow internet URLs to be specified as the logo / favicon, in addition to (rather than instead of) local relative paths.

A

[choldgraf]

Yeah - this is why I was confused. The deprecated name (html_logo) was more generic than the new name (html_logo_url) which is why I assumed the functionality had become more specific to URLs.

[2bndy5]

Huh - I never noticed a warning in any of my builds. Maybe i just missed it.

Same here, but I wouldn't have missed it since I use the switches -E -W to highlight these kind of discrepancies in my CI. Finding out that the name changed after the fact (deprecation warning never witnessed) is quite offsetting/inconvenient (wasted almost a half hour trying to track this down and address it downstream).

[jp-larose]

I just encountered this, specifically when using the haiku theme. I haven't yet looked at other themes.

[2bndy5]

I just encountered this, specifically when using the haiku theme. I haven't yet looked at other themes.

@jp-larose Can you be more specific in what exactly you encountered? TBH, I think this should be a separate bug report.

The haiku theme uses logo_url in the layout.html template, although it does not get properly used because it checks the existence of the deprecated logo var or a theme-specific theme_full_logo var:

sphinx/sphinx/themes/haiku/layout.html

Lines 37 to 48 in b88713e

	{%- if theme_full_logo != "false" %}
	<a href="{{ pathto('index') }}">
	<img class="logo" src="{{ logo_url|e }}" alt="Logo"/>
	</a>
	{%- else %}
	{%- if logo -%}
	<img class="rightlogo" src="{{ logo_url|e }}" alt="Logo"/>
	{%- endif -%}
	<h1 class="heading"><a href="{{ pathto('index') }}">
	<span>{{ shorttitle|e }}</span></a></h1>
	<h2 class="heading"><span>{{ title|striptags|e }}</span></h2>
	{%- endif %}

The haiku theme also inherits from the basic theme layout.html which uses favicon_url as expected.

sphinx/sphinx/themes/basic/layout.html

Lines 139 to 141 in b88713e

	{%- if favicon_url %}
	<link rel="icon" href="{{ favicon_url|e }}"/>
	{%- endif %}

---

May also be effecting the scrolls theme:

sphinx/sphinx/themes/scrolls/static/scrolls.css_t

Line 85 in a1c10f5

background: url({{ logo if logo else 'logo.png' }}) no-repeat center 0;

[photoniker]

Dear all,

is this bug releated to this issue? I define a html_logo = "_static/itomlogo.png". After the build you see such difference in the index.html file:

This *.png is missing in the website:

Which is at the to of the sidebar when build with Sphinx 5.

[2bndy5]

@photoniker It may be related but probably more specific to whatever theme you're using. Contact the theme administrators to inquire about compensation for Sphinx' change from logo to logo_url in the theme's HTML template(s).

[photoniker]

@2bndy5 the MDL_theme is used here.

[2bndy5]

@photoniker ok, but again you should take it up with the theme authors. I can't find that theme by googling "MDL_theme"...

[photoniker]

@photoniker ok, but again you should take it up with the theme authors. I can't find that theme by googling "MDL_theme"...

FYI https://getmdl.io/
I will contact theme.

[AA-Turner]

FYI getmdl.io
I will contact theme.

This seems to be a link to Google's Material Design Lite overview page -- do you have a link to the Sphinx theme you're using?

A

[photoniker]

FYI getmdl.io
I will contact theme.

This seems to be a link to Google's Material Design Lite overview page -- do you have a link to the Sphinx theme you're using?

A

I have the theme in the _static folder: https://github.com/itom-project/itom-project.github.io/tree/master/_static/MDL

[AA-Turner]

I can't see your conf.py or theme.conf files -- could you post a link to the directory with those and the documentation sources, please?

A

[2bndy5]

@photoniker the MDL that you keep calling a theme is not a sphinx theme. In fact, MDL is a CSS framework that is no longer maintained. What did you set html_theme in your conf.py file? I understand that itom-project/itom is a private repo.

[photoniker]

@photoniker the MDL that you keep calling a theme is not a sphinx theme. In fact, MDL is a CSS framework that is no longer maintained. What did you set html_theme in your conf.py file? I understand that itom-project/itom is a private repo.

@2bndy5 the itom project is a public repo which wwe currently move from bitbucket to GitHub. We used Sphinx for the whole Website that time. Since the last build Sphinx changed 2 major versions... And yes I also realized MDL is not maintained anymore.
However I wanted to understand If that bug is Sphinx related. Anyway we have to change the Framework for the website. Acutally the doch itself is build by Sphinx and works well using the pydata theme.

[2bndy5]

It is Sphinx related, but the bug is with the html_theme that you were using because it's HTML templates need updating...

[photoniker]

It is Sphinx related, but the bug is with the html_theme that you were using because it's HTML templates need updating...

Whould you recommend the sphinx-material theme?

[2bndy5]

Personally, no. I work on the sphinx-immaterial theme, so I'm rather biased. However, the pydata theme is ok for general usage. Many have turned to furo as a more modern theme instead of the readthedocs theme.