cc @mgeier see if this would help with what you're trying to do

Codecov Report

Merging #599 into master will decrease coverage by 0.06%.
The diff coverage is 100%.

@@            Coverage Diff             @@
##           master     #599      +/-   ##
==========================================
- Coverage   97.59%   97.52%   -0.07%     
==========================================
  Files          29       29              
  Lines        3030     3068      +38     
==========================================
+ Hits         2957     2992      +35     
- Misses         73       76       +3

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 7a4c78a...5eaeda2. Read the comment docs.

Thanks, this is definitely a step in the right direction!

It works for my use case when I use this config:

extensions = [
    'sphinx_gallery.gen_gallery',
]
sphinx_gallery_conf = {
    'css': ['gallery'],
    'examples_dirs': [],
}

However, this does still quite a few things that I don't need.
Also, ideally I would like to have users do this (instead of my extension fiddling with the config behind their backs), but for that it would be great if this could be even simpler.

An arguably less complicated way (that also works for me with this PR) would be this:

import sphinx_gallery
html_static_path = [sphinx_gallery.glr_path_static()]
html_css_files = ['gallery.css']

I think it would be great if we could reduce this even more.
For example, by only having to write something like this:

extensions = [
    'sphinx_gallery.load_style',
]

This could be implemented with a reasonably simple sub-module load_style.py (there might be a better name?):

from . import glr_path_static, __version__


def config_inited(app, config):
    path = glr_path_static()
    if path not in config.html_static_path:
        config.html_static_path.append(path)
    app.add_css_file('gallery.css')


def setup(app):
    app.require_sphinx('1.8')
    app.connect('config-inited', config_inited)
    return {
        'parallel_read_safe': True,
        'version': __version__,
    }

This can of course also be done in a follow-up PR.

I think it would be great if we could reduce this even more.
For example, by only having to write something like this:

extensions = [
'sphinx_gallery.load_style',
]

This could be simpler in some cases for people who just want to load the default set of SG styles (or whatever set we make load_style load by default), but it's less simple for main users of SG (those who want to generate a gallery):

1. It is not backward compatible for current users of SG. They need to add a new line to extensions to get the old behavior.
2. It also makes it so that they "configure SG" in two ways, via adding to extensions another line or not, and by changing gallery_conf.

Even in the case where you want to load SG style(s), we'd still want a way to say which styles to load. To configure that, you'll need to set something in sphinx_gallery_conf anyway. So now the only work we will have saved is people don't need to write examples_dirs=() in the sphinx_gallery_conf. And in doing so, we've increased the amount of testing and support we need to do (multiple extensions, entry points for us as a sphinx extension, etc.) and so does not seem worth it.

@lucyleeow I'll mark this as MRG and we can get it in. Even if we do eventually want to go a new-sub-extension route at some point, we should do it in another PR since this one already adds stuff that should be useful for folks (and does useful refactoring).

Even if we do eventually want to go a new-sub-extension route at some point, we should do it in another PR since this one already adds stuff that should be useful for folks (and does useful refactoring).

Yes please! I don't want to delay this PR (apart from my comment above).

Once this PR is merged, I will create a new PR with my suggested changes.
For now, you can have a look at 2d65445.

I think it would be great if we could reduce this even more.
For example, by only having to write something like this:

extensions = [
    'sphinx_gallery.load_style',
]

This could be simpler in some cases for people who just want to load the default set of SG styles (or whatever set we make load_style load by default), but it's less simple for main users of SG (those who want to generate a gallery)

Sorry, I haven't been clear.
I meant gen_gallery and load_style to be mutually exclusive (see 2d65445)!

It is not backward compatible for current users of SG. They need to add a new line to extensions to get the old behavior.

This would be indeed bad.

It also makes it so that they "configure SG" in two ways, via adding to extensions another line or not, and by changing gallery_conf.

This would also be quite bad.

Even in the case where you want to load SG style(s), we'd still want a way to say which styles to load. To configure that, you'll need to set something in sphinx_gallery_conf anyway.

Sure, if you want that, we can do that, see my not-yet-PR 2d65445.

So now the only work we will have saved is people don't need to write examples_dirs=() in the sphinx_gallery_conf.

Yes, and that's great!

To be more exact, we will have saved people from having to write this:

sphinx_gallery_conf = {
    'css': ['gallery'],
    'examples_dirs': [],
}

... and from loading gen_gallery, which would be a confusing thing to load if you don't actually want to generate a gallery.

And on top of that, we would have avoided to run quite a huge amount of unneeded code including setting up several unneeded Sphinx hooks (which might not be harmful, but anyway).

And in doing so, we've increased the amount of testing and support we need to do (multiple extensions, entry points for us as a sphinx extension, etc.)

Well, yes, that would be the price you as maintainers would have to pay for a great user experience!

A taste of the additional code can be seen at 2d65445, but this can probably be reduced by some refactoring (which we can discuss at a later point).

and so does not seem worth it.

That's of course your (the project maintainers') decision.
But please wait with this decision until we have discussed my upcoming PR.

@mgeier indeed 2d65445 looks like it might not be as painful as I thought, feel free to make a PR

Thanks @larsoner, I've created #601, which suggests a minimalistic implementation, but if you want, I can add a configuration option.