Just to clarify this is only needed for the case when you want to over-write existing .css files?

Just to clarify this is only needed for the case when you want to over-write existing .css files?

@lucyleeow My intuition is that that is correct. One needs to register a css file for it to be taken into account by sphinx.

What I have seen is that if I have the following "_static" directory tree in the source:

_static:
  - gallery.css
  - whatever.txt

Then we have the following results given each case:

1

html_static_path = ['_static']

Doesn't overwrite gallery.css but copies other files (like one i just named "whatever.txt") . So it seems that some files dont need registration as css does.

2

html_static_path = ['_static']
def setup(app):
    app.add_css_file('gallery.css')

Same as above, copies whatever.txt but does not overwrite gallery.css . Although my intuition is that it SHOULD overwrite the css, it just doesn't ever do.

3

html_static_path = ['_static']
def setup(app):
    app.connect('builder-inited', lambda app: app.config.html_static_path.append('_static'))
    app.add_css_file('gallery.css')

Copies whatever.txt and overwrites gallery.css .

4

def setup(app):
   app.connect('builder-inited', lambda app: app.config.html_static_path.append('_static'))
   app.add_css_file('gallery.css')

Not doing html_static_path = ['_static'] at the beginning also copies whatever.txt and overwrites the gallery.css . This is expected since after all the lambda function does the append.

It seems to me that something happens between the the config initialization and the builder initialization which erases html_static_path or maybe they are not even the same object in those two stages.

Sorry for the delay, I didn't realise it was only required to overwrite existing files. I'm in 2 minds about it...WDYT @larsoner ?
(I think I fixed the CI's, if you merge/rebase master, hopefully the tests will go green)

Have checked and can confirm #845 (comment) is all correct. I am inclined to add this to the documentation or at least amend our documentation as the following line is a bit misleading:

The static files in the path(s) listed will be copied over after the builtin Sphinx-Gallery files, so if you have a file named “gallery.css”, it will overwrite the builtin “gallery.css”.

@larsoner can you confirm if the above is true, and thus sphinx just doesn't seem to copy files over if they already exist?

I'm not sure whether or not it's true, I would confirm via trial and error using our tinybuild infrastructure

Sorry for the delay. From some digging, it seems that the sphinx gallery files are copied over AFTER paths listed in the user's project conf.py html_static_path.

We append the sphinx gallery static path to html_static_path here:

Before this line is run app.config.html_static_path contains only the paths listed in the html_static_path of the user's project conf.py file - i.e. the the user's html_static_path paths are added first.

I think app.config.html_static_path is updated with the user's config.py settings when Sphinx _init_env is run, which is before we copy glr_path_static.

Sphinx copies the static files here, looping through the self.config.html_static_path list (thus files at the end of the list will over write similarly named files at the start of the list):

    def copy_html_static_files(self, context: Dict) -> None:
        def onerror(filename: str, error: Exception) -> None:
            logger.warning(__('Failed to copy a file in html_static_file: %s: %r'),
                           filename, error)

        excluded = Matcher(self.config.exclude_patterns + ["**/.*"])
        for entry in self.config.html_static_path:
            copy_asset(path.join(self.confdir, entry),
                       path.join(self.outdir, '_static'),
                       excluded, context=context, renderer=self.templates, onerror=onerror)

What the code below does is append _static to app.config.html_static_path at the end, i.e., the order of static files being added to the app.config.html_static_path list is as follows:

1. files included in the user's config.py html_static_path
2. files in SG added glr_path_static
3. files added by the code below

def setup(app):
    app.connect('builder-inited', lambda app: app.config.html_static_path.append('_static'))

Note that the add_css_file part is not required, and from the documentation, I think it is adding files to the default HTML template, and is not related to copying over static html file.

Further, setting html_static_path in the config as well, e.g.:

html_static_path = ['_static']
def setup(app):
    app.connect('builder-inited', lambda app: app.config.html_static_path.append('_static'))

will mean that app.config.html_static_path will have _static appear twice (i.e. ['_static', <sphx_glr_static>, '_static']).

I think the 'trick' in the solution above is the 'builder-inited' part because while the app.connect() function seems to run early on in the build (before _init_env even), the appending is done later in Sphinx Builder.read()

So it seems that the code above is a bit hacky (?) and maybe we are at fault because there may be a way to append SG's static path earlier - Sphinx html_static_path documentation says:

They (the user's list of static paths) are copied to the output’s _static directory after the theme’s static files, so a file named default.css will overwrite the theme’s default.css.

I guess we have 2 options:

• investigate how to append SG static dir to app.config.html_static_path first (no idea how difficult this may be, Sphinx is magic)
• recommend that people not use gallery .css file names when adding their own .css and/or document the hack here

WDYT @larsoner ?

For now if possible let's just tell people not to use our names. Another low effort solution is to make our names more unique for example by adding _sg at the end of the filename before the extension

Thanks @larsoner

Will make those changes in a new PR, probably this weekend.

In the mean time I think I will close this PR, it's nice that a solution is documented and searchable, but I think we won't include it in our documentation. (Hope this is okay with everyone, let me know if not)

Also I had a quick look and it seems like themes may be added by the config add_html_theme, so figuring out how to add the SG static files in earlier is probably harder than just 'copy how themes do it'.

Also thanks for your work figuring this out @yjmantilla !