Links to static files defined in `conf.py` are assigned incorrectly after build

[AAriam]

Recently I posted an issue (#1325) about image icons with local paths not loading. I now found a similar problem with logo images, and think there is a general bug in generating links to static files that are defined in conf.py.

Here is a simple setup to reproduce the problem with logos:

Docs directory structure:

docs/
├── source/
│   ├── my_static_folder/
│   |    └── logo/
│   |         |── logo_light.png
│   |         └── logo_dark.png
│   ├── conf.py
│   └── index.rst
├── make.bat
└── Makefile

conf.py:

project = 'Test'
html_theme = 'pydata_sphinx_theme'
html_static_path = ['my_static_folder']
html_theme_options = {
    "logo": {
        "image_light": "my_static_folder/logo/logo_light.png",
        "image_dark": "my_static_folder/logo/logo_dark.png",
    },
}

index.rst

Homepage
========
.. image:: my_static_folder/logo/logo_dark.png

index.html after build

The logo in the header (defined in conf.py) is not loading, but the same file inserted as image in index.rst is displaying correctly:

The image file logo_dark.png, which is inserted in index.rst is put under docs/build/_images/logo_dark.png and linked correctly in the HTML file index.html. On the other hand, for the logo, the two images are put under docs/build/_static/logo/logo_dark.png and docs/build/_static/logo/logo_light.png, whereas the corresponding links in the HTML are pointing to docs/build/_static/logo_dark.png and docs/build/_static/logo_light.png, and thus the images doesn't load.

This problem also occurs when the static folder is named _static.

[michaelweinold]

I encountered the same issue recently - this is likely related to the discussion (involving @12rambau, who opened the issue) here:

• https://github.com/pydata/pydata-sphinx-theme/pull/1132#issuecomment-1448935931

What confuses me most is why it is not possible to use the Sphinx html_static_path variable in the same way that the sphinx-favicon package does:

Use a local static file as a favicon. Make sure you place your local static favicon file(s) inside a directory listed in the Sphinx “html_static_path”. For example:

So to set my favicons I have:

docs/
├── source/
│   ├── _static/
│   |    └── logo/
│   |         └── logo_dark.png
│   ├── conf.py
│   └── index.rst
└── conf.py

html_static_path = ['source/_static']
favicons = [
    {
        "rel": "icon",
        "sizes": "100x100",
        "href": "logo/logo_dark.png",
    }

Less potential for confusion about having paths relative to the config file etc. Is there a reason why this wasn't implemented for logo files also?

[12rambau]

Less potential for confusion about having paths relative to the config file etc. Is there a reason why this wasn't implemented for logo files also?

As mentioned in the linked PR/issue, we decided to align on how Sphinx itself deals with html_logo. Note as well that remaining compatible with older version of Sphinx is extremely complicated as one of the internal jinja variable has been changed between 5 and 6.

[michaelweinold]

Ok, fair enough - but then according to the documentation

html_logo If given, this must be the name of an image file (path relative to the configuration directory) that is the logo of the docs, or URL that points an image file for the logo. It is placed at the top of the sidebar; its width should therefore not exceed 200 pixels. Default: None.

New in version 0.4.1: The image file will be copied to the _static directory of the output HTML, but only if the file does not already exist there

if I have:

docs/
├── source/
│   ├── _static/
│   |    └── logo/
|   |         ├── logo_light.svg
│   |         └── logo_dark.svg
│   └── index.md
└── conf.py

html_static_path = ['source/_static']
html_theme_options = {
    "logo": {
      "image_light": "source/_static/logo/logo_light.svg",
      "image_dark": "source/_static/logo/logo_dark.svg"
    },
}

it should work? Because I am having trouble with that configuration:

[W 230629 20:56:36 web:2344] 404 GET /_static/logo_dark.svg (127.0.0.1) 0.40ms

[michaelweinold]

@12rambau, I checked further:

Irregardless of the path I use for the logo: image_light variable:

source/_static/logo/logo_light.svg
./_static/logo/logo_light.svg
logo/logo_light.svg
../../_build/html/_static/logo/logo_light.svg

the builder always ends up looking for the file at:

_static/logo_light.svg

This file, however, won't ever exist - since Sphinx (as per the documentation) copies the subdirectories of the _static directory:

docs/
├── source/
│   ├── _static/
│   |    └── logo/
|   |         ├── logo_light.svg
│   |         └── logo_dark.svg
│   └── index.md
└── conf.py

docs/
└── build/
    └── html/
         └── _static/
              └── logo/
                  ├── logo_light.svg
                  └── logo_dark.svg

In this case, this seems to be a bug with the theme, rather than a compatibility issue?

[adam-grant-hendry]

FYI, the current workaround appears to be to place the logo images directly underneath a _static folder in the src folder:

src/
├─conf.py
├─index.rst
├─_static/
│ ├─logo_dark.png   
│ └─logo_light.png  
└─__init__.py

and specify as follows in the conf.py:

html_static_path = ['_static']
html_theme_options = {
    'logo': {
        'image_light': '_static/logo_light.png',
        'image_dark': '_static/logo_dark.png',
    },
}