diff options
author | Takeshi KOMIYA <i.tkomiya@gmail.com> | 2021-01-01 17:33:34 +0300 |
---|---|---|
committer | Takeshi KOMIYA <i.tkomiya@gmail.com> | 2021-01-01 20:06:34 +0300 |
commit | c5f03980107e123210fb602f4c31f5ae950e2af4 (patch) | |
tree | 49ac5014a6eca178eadffe63a6f3b396cad3259e /sphinx/application.py | |
parent | 7ecf6b88aa5ddaed552527d2ef60f1bd35e98ddc (diff) |
Close #8634: html: Allow to change the order of JS/CSS
`Sphinx.add_js_file()` and `Sphinx.add_css_file()` take `priority`
argument to change the order of JS/CSS files.
Diffstat (limited to 'sphinx/application.py')
-rw-r--r-- | sphinx/application.py | 58 |
1 files changed, 43 insertions, 15 deletions
diff --git a/sphinx/application.py b/sphinx/application.py index 2253ce306..39ab93ed1 100644 --- a/sphinx/application.py +++ b/sphinx/application.py @@ -916,21 +916,21 @@ class Sphinx: """ self.registry.add_post_transform(transform) - def add_javascript(self, filename: str, **kwargs: str) -> None: + def add_javascript(self, filename: str, **kwargs: Any) -> None: """An alias of :meth:`add_js_file`.""" warnings.warn('The app.add_javascript() is deprecated. ' 'Please use app.add_js_file() instead.', RemovedInSphinx40Warning, stacklevel=2) self.add_js_file(filename, **kwargs) - def add_js_file(self, filename: str, **kwargs: str) -> None: + def add_js_file(self, filename: str, priority: int = 500, **kwargs: Any) -> None: """Register a JavaScript file to include in the HTML output. Add *filename* to the list of JavaScript files that the default HTML - template will include. The filename must be relative to the HTML - static path , or a full URI with scheme. If the keyword argument - ``body`` is given, its value will be added between the - ``<script>`` tags. Extra keyword arguments are included as + template will include in order of *priority* (ascending). The filename + must be relative to the HTML static path , or a full URI with scheme. + If the keyword argument ``body`` is given, its value will be added + between the ``<script>`` tags. Extra keyword arguments are included as attributes of the ``<script>`` tag. Example:: @@ -944,23 +944,38 @@ class Sphinx: app.add_js_file(None, body="var myVariable = 'foo';") # => <script>var myVariable = 'foo';</script> + .. list-table:: priority range for JavaScript files + :widths: 20,80 + + * - Priority + - Main purpose in Sphinx + * - 200 + - default priority for built-in JavaScript files + * - 500 + - default priority for extensions + * - 800 + - default priority for :confval:`html_js_files` + .. versionadded:: 0.5 .. versionchanged:: 1.8 Renamed from ``app.add_javascript()``. And it allows keyword arguments as attributes of script tag. + + .. versionchanged:: 3.5 + Take priority argument. """ - self.registry.add_js_file(filename, **kwargs) + self.registry.add_js_file(filename, priority=priority, **kwargs) if hasattr(self.builder, 'add_js_file'): - self.builder.add_js_file(filename, **kwargs) # type: ignore + self.builder.add_js_file(filename, priority=priority, **kwargs) # type: ignore - def add_css_file(self, filename: str, **kwargs: str) -> None: + def add_css_file(self, filename: str, priority: int = 500, **kwargs: Any) -> None: """Register a stylesheet to include in the HTML output. Add *filename* to the list of CSS files that the default HTML template - will include. The filename must be relative to the HTML static path, - or a full URI with scheme. The keyword arguments are also accepted for - attributes of ``<link>`` tag. + will include in order of *priority* (ascending). The filename must be + relative to the HTML static path, or a full URI with scheme. The + eyword arguments are also accepted for attributes of ``<link>`` tag. Example:: @@ -975,6 +990,16 @@ class Sphinx: # => <link rel="alternate stylesheet" href="_static/fancy.css" # type="text/css" title="fancy" /> + .. list-table:: priority range for CSS files + :widths: 20,80 + + * - Priority + - Main purpose in Sphinx + * - 500 + - default priority for extensions + * - 800 + - default priority for :confval:`html_css_files` + .. versionadded:: 1.0 .. versionchanged:: 1.6 @@ -987,11 +1012,14 @@ class Sphinx: .. versionchanged:: 1.8 Renamed from ``app.add_stylesheet()``. And it allows keyword arguments as attributes of link tag. + + .. versionchanged:: 3.5 + Take priority argument. """ logger.debug('[app] adding stylesheet: %r', filename) - self.registry.add_css_files(filename, **kwargs) + self.registry.add_css_files(filename, priority=priority, **kwargs) if hasattr(self.builder, 'add_css_file'): - self.builder.add_css_file(filename, **kwargs) # type: ignore + self.builder.add_css_file(filename, priority=priority, **kwargs) # type: ignore def add_stylesheet(self, filename: str, alternate: bool = False, title: str = None ) -> None: @@ -1000,7 +1028,7 @@ class Sphinx: 'Please use app.add_css_file() instead.', RemovedInSphinx40Warning, stacklevel=2) - attributes = {} # type: Dict[str, str] + attributes = {} # type: Dict[str, Any] if alternate: attributes['rel'] = 'alternate stylesheet' else: |