Fix support for html logo and favicon as url

[tronical]

Subject: Fix support for html logo and favicon as url

Feature or Bugfix

• Bugfix

Purpose

Stripping the url in the context setup means that any later isurl()
calls will fail and logo_url will always be a local relative path.

[tk0miya]

Could you merge the HEAD of 4.x branch please?

[tronical]

Could you merge the HEAD of 4.x branch please?

Will do. I've pushed the merge as well as the assignment fixes. I need a bit more time for the test :)

[tk0miya]

Thank you for update. Merging now!

[ViktorHaag]

Hello @tk0miya and @tronical -- I believe this fix has a problem. I will try to state it as I understand the situation.

If you pull your html_logo (or favicon) from a file in your source directory, but someplace other than the conf root, then this fix causes an issue.

The configuration documentation for the HTML writer makes it clear that html_logo and html_favicon should be either file paths (relative to the directory with conf.py) or a URL. In this case, let's assume both are files.

During building both these files will be copied over into the output into the _static directory. Let us assume that I have this in my conf.py:

html_logo = os.path.join( ".static", "logo.png" )
html_favicon = os.path.join( ".static", "favicon.ico" )

That is, in my configuration directory, I have a .static subdirectory where I put my static files (including the logo and favicon files), and this entire directory gets copied over to _static in the output. I can verify that, even with this change, the copying process during build works -- the resource files get found in my .static input directory and copied over to the _static subdirectory in the output as expected.

However, now the problem comes with setting the values for logo and logo_url (and the favicon variable values as well) that will get passed into the templating engine. Before this change, when building the writing context for output we used basename to strip off any leading path information from the original input location found in html_logo. This means that we could find the logo file in a predictable place: the logo file basename, relative to the output static directory.

However, now that we're no longer only taking the basename, the writer is expecting the file to account for the entire input file path to the logo file even though it doesn't write that full path into the output during building.

That is:

• building takes .static/logo.png and copies it to _static/logo.png
• writing expects to now find the logo in _static/.static/logo.png because it uses the entire input file path, and not just the basename

I'm really not sure how to fix this problem. There is a workaround -- if you put the logo (and favicon) in your file path in the same directory as the conf file, then there's no preceding relative path in the input declaration of html_logo, and therefore no relative path that gets re-used in the writer output when making the HTML. This seems like a sub-optimal workaround, however. It seems very useful to be able to specify a configurable path for the input file and not have that path used in the output when building the output HTML (but rather, expect to have the files directly within the _static output directory).

I'm quite sorry for the length of this explanation and for commenting on a closed PR.

@tk0miya --- please, what would you like me to do as a next step? Should I take this comment and turn it into a regression issue?

[tronical]

Great problem description. Sounds like a valid use-case and therefore regression to me. I could make a change that applies basename again if the supplied values are not URLs. What do you think?

[ViktorHaag]

I think that might do. The documentation for the Templating says this:

logo
The path to the HTML logo image in the static path, or URL to the logo, or ''.
Deprecated since version 4.0: Recommend to use logo_url instead.

logo_url
The relative path to the HTML logo image from the current document, or URL to the logo, or ''.
New in version 4.0.

This seems to indicate to me that we expect logo to be a file path relative to the static output directory for the logo file, and that we expect logo_url to be either a relative URL relative to the current page, or an absolute URL to the logo.

I suspect, therefore, that you're correct that base naming would work when building the values to passed down to the templating engine -- the writer output expects the simple "logo" file location to be relative to the output static directory when it's building either the path value, or the URL value.

[tupui]

@tronical @ViktorHaag, could this be the cause of the missing logo in our recent builds over at SciPy? We did not change anything to the config and have html_logo = '_static/scipyshiny_small.png', and the missing logo started with yesterdays release (4.1).

scipy/scipy#14396

[ViktorHaag]

@tupui I suspect it might. From what I can tell, if you set html_logo = '_static/scipyshiny_small.png', then I would expect that when HTML gets written to the output, it might actually be looking for the logo in /_static/_static/scipyshiny_small.png...?

[tupui]

@tupui I suspect it might. From what I can tell, if you set html_logo = '_static/scipyshiny_small.png', then I would expect that when HTML gets written to the output, it might actually be looking for the logo in /_static/_static/scipyshiny_small.png...?

Just checked and this is the case! Thanks for your help. So I can also confirm the regression here.

[ViktorHaag]

As we have a replication from SciPy, I've created an issue for going forward: #9438