IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

add_stylesheet() allows additional attributes

Browse Source
This commit is contained in:
Takeshi KOMIYA 2018-04-03 11:32:20 +09:00
parent 6030e7390d
commit c5d6942b88
4 changed files with 51 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
CHANGES
View File

@ -58,6 +58,7 @@ Features added
* LaTeX: new key ``'fvset'`` for :confval:`latex_elements`. For
XeLaTeX/LuaLaTeX its default sets ``fanvyvrb`` to use normal, not small,
fontsize in code-blocks (refs: #4793)
* ``app.add_stylesheet()`` allows additional attributes
Bugs fixed
----------

36
sphinx/application.py
View File

@ -1001,13 +1001,27 @@ class Sphinx(object):
StandaloneHTMLBuilder.script_files.append(
posixpath.join('_static', filename))
def add_stylesheet(self, filename, alternate=False, title=None):
# type: (unicode, bool, unicode) -> None
def add_stylesheet(self, filename, **kwargs):
# type: (unicode, **unicode) -> 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. Like for :meth:`add_javascript`, the filename must be
relative to the HTML static path, or a full URI with scheme.
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.
Example::
app.add_stylesheet('custom.css')
# => <link rel="stylesheet" href="_static/custom.css" type="text/css" />
app.add_stylesheet('print.css', media='print')
# => <link rel="stylesheet" href="_static/print.css"
# type="text/css" media="print" />
app.add_stylesheet('fancy.css', rel='alternate stylesheet', title='fancy')
# => <link rel="alternate stylesheet" href="_static/fancy.css"
# type="text/css" title="fancy" />
.. versionadded:: 1.0
@ -1017,16 +1031,20 @@ class Sphinx(object):
arguments. The default is no title and *alternate* = ``False``. For
more information, refer to the `documentation
<https://mdn.io/Web/CSS/Alternative_style_sheets>`__.
.. versionchanged:: 1.8
Allows keyword arguments as attributes of link tag.
"""
logger.debug('[app] adding stylesheet: %r', filename)
from sphinx.builders.html import StandaloneHTMLBuilder, Stylesheet
if '://' not in filename:
filename = posixpath.join('_static', filename)
if alternate:
rel = u'alternate stylesheet'
else:
rel = u'stylesheet'
css = Stylesheet(filename, title, rel) # type: ignore
if kwargs.pop('alternate', None):
warnings.warn('The alternate option for app.add_stylesheet() is deprecated. '
'Please use rel="alternate stylesheet" option instead.',
RemovedInSphinx30Warning)
kwargs['rel'] = 'alternate stylesheet'
css = Stylesheet(filename, **kwargs)
StandaloneHTMLBuilder.css_files.append(css)
def add_latex_package(self, packagename, options=None):

26
sphinx/builders/html.py
View File

@ -50,6 +50,7 @@ from sphinx.util.matching import patmatch, Matcher, DOTFILES
from sphinx.util.nodes import inline_all_toctrees
from sphinx.util.osutil import SEP, os_path, relative_uri, ensuredir, \
movefile, copyfile
from sphinx.util.pycompat import htmlescape
from sphinx.writers.html import HTMLWriter, HTMLTranslator
if False:
@ -101,7 +102,7 @@ class CSSContainer(list):
if isinstance(obj, Stylesheet):
super(CSSContainer, self).append(obj)
else:
super(CSSContainer, self).append(Stylesheet(obj, None, 'stylesheet')) # type: ignore # NOQA
super(CSSContainer, self).append(Stylesheet(obj))
def insert(self, index, obj):
# type: (int, Union[unicode, Stylesheet]) -> None
@ -111,7 +112,7 @@ class CSSContainer(list):
if isinstance(obj, Stylesheet):
super(CSSContainer, self).insert(index, obj)
else:
super(CSSContainer, self).insert(index, Stylesheet(obj, None, 'stylesheet')) # type: ignore # NOQA
super(CSSContainer, self).insert(index, Stylesheet(obj))
def extend(self, other): # type: ignore
# type: (List[Union[unicode, Stylesheet]]) -> None
@ -144,12 +145,18 @@ class Stylesheet(text_type):
its filename (str).
"""
def __new__(cls, filename, title, rel):
attributes = None # type: Dict[unicode, unicode]
filename = None # type: unicode
def __new__(cls, filename, *args, **attributes):
# type: (unicode, unicode, unicode) -> None
self = text_type.__new__(cls, filename) # type: ignore
self.filename = filename
self.title = title
self.rel = rel
self.attributes = attributes
self.attributes.setdefault('rel', 'stylesheet')
if args: # old style arguments (rel, title)
self.attributes['rel'] = args[0]
self.attributes['title'] = args[1]
return self
@ -988,6 +995,15 @@ class StandaloneHTMLBuilder(Builder):
return uri
ctx['pathto'] = pathto
def css_tag(css):
# type: (Stylesheet) -> unicode
attrs = ['%s="%s"' % (key, htmlescape(value, True))
for key, value in css.attributes.items()
if value is not None]
attrs.append('href="%s"' % pathto(css.filename, resource=True))
return '<link %s />' % ' '.join(attrs)
ctx['css_tag'] = css_tag
def hasdoc(name):
# type: (unicode) -> bool
if name in self.env.all_docs:

4
sphinx/themes/basic/layout.html
View File

@ -97,8 +97,8 @@
<link rel="stylesheet" href="{{ pathto('_static/' + style, 1) }}" type="text/css" />
<link rel="stylesheet" href="{{ pathto('_static/pygments.css', 1) }}" type="text/css" />
{%- for css in css_files %}
{%- if css|attr("rel") %}
<link rel="{{ css.rel }}" href="{{ pathto(css.filename, 1) }}" type="text/css"{% if css.title is not none %} title="{{ css.title }}"{% endif %} />
{%- if css|attr("filename") %}
{{ css_tag(css) }}
{%- else %}
<link rel="stylesheet" href="{{ pathto(css, 1) }}" type="text/css" />
{%- endif %}