Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Closed
ViktorHaag opened this issue Dec 31, 2022 · 21 comments · Fixed by #11063
Closed

Comments

@ViktorHaag
Copy link
Contributor

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
Copy link
Contributor

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
Copy link
Member

AA-Turner commented Jan 2, 2023

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
Copy link
Contributor

choldgraf commented Jan 2, 2023

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
Copy link
Member

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
Copy link
Contributor

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.

komainu8 pushed a commit to groonga/groonga that referenced this issue Jan 5, 2023
Because pydata-sphinx-theme occurs problem of
pydata/pydata-sphinx-theme#1094
when we use Sphinx 6.0.0.

The cause of this problem is the following change of Sphinx.

* sphinx-doc/sphinx#11062
* sphinx-doc/sphinx#11063

Therefore we use Sphinx 5.x until pydata-sphinx-theme resolve
this problem.
kou pushed a commit to groonga/groonga that referenced this issue Jan 5, 2023
Because pydata-sphinx-theme occurs problem of
pydata/pydata-sphinx-theme#1094 when we use
Sphinx 6.0.0.

The cause of this problem is the following change of Sphinx.

* sphinx-doc/sphinx#11062
* sphinx-doc/sphinx#11063

Therefore we use Sphinx 5.x until pydata-sphinx-theme resolve this
problem.
@2bndy5
Copy link

2bndy5 commented Jan 19, 2023

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
Copy link

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

@2bndy5
Copy link

2bndy5 commented Jan 31, 2023

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:

{%- 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.

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


May also be effecting the scrolls theme:

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

raulcd pushed a commit to apache/arrow that referenced this issue Apr 18, 2023
…= 6 (#35194)

### Rationale for this change

Sphinx dropped support for the `logo` property in release 6.  See sphinx-doc/sphinx#11062  Instead we are supposed to use `logo_url` which has been available since release 4.

### What changes are included in this PR?

Change from `logo` to `logo_url`

### Are these changes tested?

There was a CI test that was failing so yes.

### Are there any user-facing changes?

No.  We already required `sphinx >= 4` and since `logo_url` is available in 4 we should not need to update the minimum sphinx version.
* Closes: #35192

Authored-by: Weston Pace <weston.pace@gmail.com>
Signed-off-by: Raúl Cumplido <raulcumplido@gmail.com>
raulcd pushed a commit to apache/arrow that referenced this issue Apr 19, 2023
…= 6 (#35194)

### Rationale for this change

Sphinx dropped support for the `logo` property in release 6.  See sphinx-doc/sphinx#11062  Instead we are supposed to use `logo_url` which has been available since release 4.

### What changes are included in this PR?

Change from `logo` to `logo_url`

### Are these changes tested?

There was a CI test that was failing so yes.

### Are there any user-facing changes?

No.  We already required `sphinx >= 4` and since `logo_url` is available in 4 we should not need to update the minimum sphinx version.
* Closes: #35192

Authored-by: Weston Pace <weston.pace@gmail.com>
Signed-off-by: Raúl Cumplido <raulcumplido@gmail.com>
@AA-Turner AA-Turner added this to the some future version milestone Apr 29, 2023
liujiacheng777 pushed a commit to LoongArch-Python/arrow that referenced this issue May 11, 2023
…hinx >= 6 (apache#35194)

### Rationale for this change

Sphinx dropped support for the `logo` property in release 6.  See sphinx-doc/sphinx#11062  Instead we are supposed to use `logo_url` which has been available since release 4.

### What changes are included in this PR?

Change from `logo` to `logo_url`

### Are these changes tested?

There was a CI test that was failing so yes.

### Are there any user-facing changes?

No.  We already required `sphinx >= 4` and since `logo_url` is available in 4 we should not need to update the minimum sphinx version.
* Closes: apache#35192

Authored-by: Weston Pace <weston.pace@gmail.com>
Signed-off-by: Raúl Cumplido <raulcumplido@gmail.com>
ArgusLi pushed a commit to Bit-Quill/arrow that referenced this issue May 15, 2023
…hinx >= 6 (apache#35194)

### Rationale for this change

Sphinx dropped support for the `logo` property in release 6.  See sphinx-doc/sphinx#11062  Instead we are supposed to use `logo_url` which has been available since release 4.

### What changes are included in this PR?

Change from `logo` to `logo_url`

### Are these changes tested?

There was a CI test that was failing so yes.

### Are there any user-facing changes?

No.  We already required `sphinx >= 4` and since `logo_url` is available in 4 we should not need to update the minimum sphinx version.
* Closes: apache#35192

Authored-by: Weston Pace <weston.pace@gmail.com>
Signed-off-by: Raúl Cumplido <raulcumplido@gmail.com>
rtpsw pushed a commit to rtpsw/arrow that referenced this issue May 16, 2023
…hinx >= 6 (apache#35194)

### Rationale for this change

Sphinx dropped support for the `logo` property in release 6.  See sphinx-doc/sphinx#11062  Instead we are supposed to use `logo_url` which has been available since release 4.

### What changes are included in this PR?

Change from `logo` to `logo_url`

### Are these changes tested?

There was a CI test that was failing so yes.

### Are there any user-facing changes?

No.  We already required `sphinx >= 4` and since `logo_url` is available in 4 we should not need to update the minimum sphinx version.
* Closes: apache#35192

Authored-by: Weston Pace <weston.pace@gmail.com>
Signed-off-by: Raúl Cumplido <raulcumplido@gmail.com>
@photoniker
Copy link

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:
image

This *.png is missing in the website:
image
Which is at the to of the sidebar when build with Sphinx 5.
image

@2bndy5
Copy link

2bndy5 commented May 16, 2023

@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
Copy link

@2bndy5 the MDL_theme is used here.

@2bndy5
Copy link

2bndy5 commented May 16, 2023

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

@photoniker
Copy link

@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
Copy link
Member

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
Copy link

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
Copy link
Member

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
Copy link

2bndy5 commented May 17, 2023

@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
Copy link

@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
Copy link

2bndy5 commented May 17, 2023

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

@photoniker
Copy link

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
Copy link

2bndy5 commented May 17, 2023

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.

photoniker pushed a commit to itom-project/itom-project.github.io that referenced this issue May 22, 2023
Totktonada added a commit to luafun/luafun.github.io that referenced this issue Aug 30, 2023
The previous commit was built using Sphinx 7.0.1. As result, the logo
disappears. I can't find a solution using the modern Shpinx, so rebuilt
the documentation using 4.4.0.

It seems it is somehow related to configuration options renaming and how
Sphinx themes follow these changes, see [1].

[1]: sphinx-doc/sphinx#11062
Totktonada added a commit to luafun/luafun.github.io that referenced this issue Aug 30, 2023
The previous commit was built using Sphinx 7.0.1. As result, the logo
disappears. I can't find a solution using the modern Shpinx, so rebuilt
the documentation using 4.4.0.

It seems it is somehow related to configuration options renaming and how
Sphinx themes follow these changes, see [1].

[1]: sphinx-doc/sphinx#11062
@github-actions github-actions bot locked as resolved and limited conversation to collaborators Feb 12, 2024
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
None yet
Projects
None yet
Development

Successfully merging a pull request may close this issue.

6 participants