Add a theme option for additional CSS files

[exhuma]

I have just one simple class to add to the CSS. After looking through the source-code, I found no theme option to add a CSS file. Also extending the theme did not work for some reason. It kept complaining that no "theme.conf" file is found even though there was one. But that may be an issue with sphinx itself.

I have given up now and will leave the output as-is, but it does make parts of the documentation less readable than it could be.

Having a theme option to append additional CSS files to the output would be really nice.

[Blendify]

Do you mean html_static_path http://www.sphinx-doc.org/en/1.5.1/config.html?highlight=html_static_path#confval-html_static_path

[exhuma]

No, not the static path. I was thinking about a configuration option like extra_stylesheets which would get appended at the end of the HEAD block. For example:

html_theme_options = {
    'extra_stylesheets': ['_static/mycustom.css']
}

Which would then result in the file mycustom.css to be linked in the final HTML document (possibly after all other stylesheets).

Whether this needs to be a list of stylesheets is questionable. Usually one is enough. The idea with extra_stylesheets as list comes from another theme, but I can't remember which one anymore. But I remember using a theme in the past which allowed this.

[Blendify]

I think you are looking for something like http://www.sphinx-doc.org/en/stable/templating.html?highlight=extrahead ?

[Blendify]

Closing this, we can re-open if this is an issue but I do not think there is an issue here.

[exhuma]

Sorry for the late reply, but I don't agree that the link given in the above comment is a good solution. From what I understand, this would still require me to create a new theme, extend sphinx_rtd_theme and override the blocks.

The idea behind this request is that it would not be necessary to override the theme completely just to add a couple of custom CSS rules.

At the current state, there is no way that I can see to add CSS files via the config (that is, without extending the theme).

I've been trying the extra_stylesheets which I mentioned above in an existing theme, but for the life of me I can't find it. Yet I'm sure I've seen it in another theme... or I've been dreaming about it... ;)

I'm fine with it by the way if you decide to refuse this feature request and expect users to override the theme. I just wanted to add some details, as it seems that in the above comments, we've been talking about two different things (one being the sphinx theme config, and the other being overriding the theme altogether).

[Blendify]

Try something like this in the conf.py file you can change the file paths to your liking:

html_static_path = ["../resources/theme"]

def setup(app):
        app.add_stylesheet("css/your_css-file.css")

[exhuma]

This works. Thanks!

I was just looking for this in the sphinx docs (the fact that a setup function can be provided) but can't find it. I'm curious to find out what else is possible with this.

[Blendify]

Have a look at http://www.sphinx-doc.org/en/stable/extdev/appapi.html?

[exhuma]

This is cool. The fact that you can write a setup function in conf.py is a bit hidden away in the core-events section.

Thanks for this! 👍