Setting html_context['css_files'] renders add_stylesheet() inoperative

[mgeier]

When I use something like this in my conf.py:

html_static_path = ['_static']
html_context = {
    'css_files': ['_static/my_css_file.css'],
}

... and an extension uses add_stylesheet(), latter has no effect.

Is this intentional?

I would expect the css_files mentioned in conf.py to be appended to the list of CSS files from the theme and from extensions.

[tk0miya]

I don't know the behavior is intentional or not.

Now sphinx provides add_stylesheet() API to add css files.
But html_context["css_files"] is undocumented internal key to manage css files. I think it is not proper way to add CSS files.
So your problem is unexpected, but undefined behavior.

Any reason to use html_context["css_files"] instead of add_stylesheet()?

[mgeier]

I think the one obvious way for a "normal" user to provide custom settings to Sphinx is defining variables (e.g. html_title or latex_elements) in conf.py.

OTOH, the one obvious way for "extension writers" to extend (and "enhance") the user-specified settings is to use the application API from the extension's setup() function, e.g. by using app.add_stylesheet().

I know it's also possible for "normal" users to define a setup() function directly in their conf.py, getting access to the full application API. This is great, but I think it should only be used for very specialized use cases. It shouldn't be the "one obvious way to do it". It shouldn't become the default for "normal" users. Casual users should never have to worry about a setup() function.

Adding style definitions to the existing CSS definitions is IMHO a quite "normal" thing to do for a "normal" user, therefore it should be possible by simply assigning to a variable in conf.py.
It seems to me that html_context["css_files"] is a reasonable place to do that.
But I would, as I said initially, expect the user settings to be appended to the settings given by Sphinx, the theme and any extensions. This would be the same behavior as when assigning to latex_elements['preamble'] (which doesn't replace the existing preamble but appends to it).

If for some technical reason html_context cannot be modified as I suggested in my original comment (which I doubt very much), a new configuration variable should probably be created.

See also my comments readthedocs/readthedocs.org#2116 (comment) and readthedocs/readthedocs.org#2116 (comment).

[willingc]

@tk0miya Let me add a bit of background on the request. Project Jupyter/IPython notebooks rely on using @mgeier's nbsphinx package for including notebooks in Sphinx documentation. This workflow has worked really well for us except for unexpected CSS rendering breakage from time to time. The devs on Sphinx, ReadTheDocs (@ericholscher, @agjohnson), and nbsphinx are doing great work. I'm wondering what we can do to make it easier for Jupyter and our users create docs using nbsphinx and custom themes to simplify configuration (ideally in conf.py). Thanks all. Looking forward to everyone's thoughts.:smile:

[ericholscher]

Sounds like what folks want is just another setting like css_files that you can set, and it has the same outcome as doing:

def setup():
    app.add_stylesheet('foo.css')

Personally I don't think the extension solution is bad, and allows full access to the app API, which a settings file doesn't support.

You extension could easily include the add_stylesheet call, so users would never had to set it.

[mgeier]

@ericholscher Sure, the extension could easily use add_stylesheet(), and that's exactly what the function was made for. But in this issue I'm not talking about extensions, I'm talking about having to abuse extension-features as a normal user.

And yes, a css_files option (or similar) that does not overwrite existing CSS settings would solve the issue. From a user's perspective I see no reason why there should be another setting in addition to html_context["css_files"], but if there is a technical reason for a separate setting, we should have it!

[benjaoming]

I'm trying to add a custom stylesheet on RTD. I do the following:

on_rtd = os.environ.get('READTHEDOCS', None) == 'True'

if not on_rtd:  # only import and set the theme if we're building docs locally
    import sphinx_rtd_theme
    html_theme = 'sphinx_rtd_theme'
    html_theme_path = ['.', sphinx_rtd_theme.get_html_theme_path()]

html_context = {
    'css_files': [
        '_static/theme_overrides.css',  # override wide tables in RTD theme
    ],
}

But this means that when building on the RTD server, my build doesn't contain the theme's stylesheet. Building locally works.

Based on my intuition of reading the configuration, I am surprised to see that things work locally and then break when deployed to the RTD servers.

I think the issue is legit. Additionally, if the behaviour is undefined, then it's more okay to introduce a definition. If there was an existing definition or convention, it would be a problem.