Adding CSS and javascript files from extensions

[Vladimir Goncharov]

Hello!

(This is a continuation of https://github.com/sphinx-doc/sphinx/issues/1379)

I'm developing an extension for drawing railroad diagrams in svg. So there's a css file with default styles for diagrams which I'd like to see included on every page that uses functionality of my plugin. I, however, was not able to find any API for doing this.

I'm looking for a solution that:

• will not require user to adjust 'html_static_path' in theirs conf.py. That is, including my extension to the 'extensions' list should be enough for it to work;
• will allow user to override the default stylesheet by providing their own one;
• (optionally) will only include my css to the pages that actually use directives from my plugin.

Public API don't do what I want it to do:

• 'app.add_stylesheet' requires that "the filename must be relative to the HTML static path, or a full URI with scheme". Naturally, none of my extension's directory are on HTML static path, thus calling 'app.add_stylesheet' is not enough by itself;
  
• modifying 'app.config.html_static_path' from the setup function of my extension only works if user have not redefined 'html_static_path' in theirs conf.py. This happens because variables from conf.py override default config variables after all extensions re loaded;
• modifying 'app.config._raw_config['html_static_path']' does exactly what I want, however, '_raw_config' is not part of the public API;
  
• modifying 'app.config.html_static_path' from 'builder-inited' hook seems to work (that's how exhale does this) but Shimizukawa suggests that extensions should not modify 'app.config'.
  

So, there seem to be no way to add custom stylesheets and javascript files from extensions properly.

I propose either developing an official API for this or stating that modifying 'app.config' from 'builder-inited' is fine (or maybe we should use 'config-inited' for this?) and documenting this usage.

[Komiya Takeshi]

Hi,

I guess your goal is copying CSS files properly, not modifying config
object. Hence it is better to provide a way to copy them easily.
Is this right?

At present, you can do it with following code:

```
from sphinx.util.fileutil import copy_asset

def copy_asset_files(app, exc):
asset_files = [...]
if exc is None: # build succeeded
for path in asset_files:
copy_asset(path, os.path.join(app.outdir, '_static'))

def setup(app):
app.connect('build-finished', copy_asset_files)
```

I think this code is enough simple. What do you think? Would you like
to add another API to do that?

Thanks,
Takeshi KOMIYA
2018年11月19日(月) 2:42 Vladimir Goncharov <dev....@gmail.com>:

> --
> You received this message because you are subscribed to the Google Groups "sphinx-users" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to sphinx-users...@googlegroups.com.
> To post to this group, send email to sphinx...@googlegroups.com.
> Visit this group at https://groups.google.com/group/sphinx-users.
> For more options, visit https://groups.google.com/d/optout.

[Matthias Geier]

Hi Vladimir.

On Sun, Nov 18, 2018 at 6:42 PM Vladimir Goncharov wrote:
>
> Hello!
>
> (This is a continuation of https://github.com/sphinx-doc/sphinx/issues/1379)
>
> I'm developing an extension for drawing railroad diagrams in svg. So there's a css file with default styles for diagrams which I'd like to see included on every page that uses functionality of my plugin. I, however, was not able to find any API for doing this.
>
> I'm looking for a solution that:
>
> will not require user to adjust 'html_static_path' in theirs conf.py. That is, including my extension to the 'extensions' list should be enough for it to work;
> will allow user to override the default stylesheet by providing their own one;
> (optionally) will only include my css to the pages that actually use directives from my plugin.

I have come up with a solution for the last point:
https://github.com/spatialaudio/nbsphinx/blob/ca978181ecb045974d399b522c03b96305b85290/src/nbsphinx.py#L1488-L1498

The directives set a flag (in my case "nbsphinx_include_css") and on
each page where this is present, my extension copies some CSS code
directly to the "body" of the HTML (in "html-page-context").

This isn't really easy to override by the user, though.

The user has to use more specific CSS selectors in their CSS files or
"!important" in order to override.

I'm wondering if using "sphinx.util.fileutil.copy_asset()" would be
better (as Takeshi suggested).

> Public API don't do what I want it to do:
>
> 'app.add_stylesheet' requires that "the filename must be relative to the HTML static path, or a full URI with scheme". Naturally, none of my extension's directory are on HTML static path, thus calling 'app.add_stylesheet' is not enough by itself;
> modifying 'app.config.html_static_path' from the setup function of my extension only works if user have not redefined 'html_static_path' in theirs conf.py. This happens because variables from conf.py override default config variables after all extensions re loaded;
> modifying 'app.config._raw_config['html_static_path']' does exactly what I want, however, '_raw_config' is not part of the public API;

Yes, that's a bit of a sad story.
It's obviously not part of the public API, but it seems to work quite well ...

I'm also using it in a current pull request, because the old way of
manipulating "config.latex_elements" stopped working in a recent
Sphinx commit:
https://github.com/spatialaudio/nbsphinx/pull/250

> modifying 'app.config.html_static_path' from 'builder-inited' hook seems to work (that's how exhale does this) but Shimizukawa suggests that extensions should not modify 'app.config'.
>
> So, there seem to be no way to add custom stylesheets and javascript files from extensions properly.
>
> I propose either developing an official API for this or stating that modifying 'app.config' from 'builder-inited' is fine (or maybe we should use 'config-inited' for this?) and documenting this usage.

There was a bit of discussion a few years ago about possibly changing
the way the configuration options are consumed by Sphinx:
https://github.com/sphinx-doc/sphinx/issues/2162#issuecomment-168629682

I've created an issue as a reminder, but it looks like nothing has
happened in the meantime:
https://github.com/sphinx-doc/sphinx/issues/2255

cheers,
Matthias

[Juna Luzi]

I've been stuck on this for the last two days. This helped a lot @Komiya Takeshi.

> To unsubscribe from this group and stop receiving emails from it, send an email to sphinx...@googlegroups.com.

[Daniel Scott]

To unsubscribe from this group and stop receiving emails from it, send an email to sphinx-users...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/sphinx-users/fb35f626-94ae-4c18-98ea-0c600d4aa6d8o%40googlegroups.com.