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

Merge pull request #4815 from tk0miya/refine_add_css_file

Browse Source 
Refine adding CSS files
This commit is contained in:
Takeshi KOMIYA 2018-04-13 00:21:33 +09:00 committed by GitHub
commit c35eb6fade
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
13 changed files with 182 additions and 25 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
CHANGES
View File

@ -35,6 +35,7 @@ Deprecated
* #2157: helper function ``warn()`` for HTML themes is deprecated
* ``env._nitpick_ignore`` is deprecated
* ``app.override_domain()`` is deprecated
* ``app.add_stylesheet()`` is deprecated
For more details, see `deprecation APIs list
<http://www.sphinx-doc.org/en/master/extdev/index.html#deprecated-apis>`_
@ -58,6 +59,8 @@ 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)
* Add :confval:`html_css_files` and :confval:`epub_css_files` for adding CSS
files from configuration
Bugs fixed
----------

27
doc/config.rst
View File

@ -59,9 +59,6 @@ Important points to note:
Note that the current builder tag is not available in ``conf.py``, as it is
created *after* the builder is initialized.
.. seealso:: Additional configurations, such as adding stylesheets,
javascripts, builders, etc. can be made through the :doc:`/extdev/appapi`.
General configuration
---------------------
@ -846,6 +843,22 @@ that use Sphinx's HTMLWriter class.
The image file will be copied to the ``_static`` directory of the output
HTML, but only if the file does not already exist there.
.. confval:: html_css_files
A list of CSS files. The entry must be a *filename* string or a tuple
containing the *filename* string and the *attributes* dictionary. The
*filename* must be relative to the :confval:`html_static_path`, or a full URI
with scheme like ``http://example.org/style.css``. The *attributes* is used
for attributes of ``<link>`` tag. It defaults to an empty list.
Example::
html_css_files = ['custom.css'
'https://example.com/css/custom.css',
('print.css', {'media': 'print'})]
.. versionadded:: 1.8
.. confval:: html_static_path
A list of paths that contain custom static files (such as style
@ -1511,6 +1524,14 @@ the `Dublin Core metadata <http://dublincore.org/>`_.
.. versionadded:: 1.1
.. confval:: epub_css_files
A list of CSS files. The entry must be a *filename* string or a tuple
containing the *filename* string and the *attributes* dictionary. For more
information, see :confval:`html_css_files`.
.. versionadded:: 1.8
.. confval:: epub_guide
Meta data for the guide element of :file:`content.opf`. This is a

5
doc/extdev/index.rst
View File

@ -114,6 +114,11 @@ The following is a list of deprecated interface.
- (will be) Removed
- Alternatives
* - :meth:`~sphinx.application.Sphinx.add_stylesheet()`
- 1.8
- 4.0
- :meth:`~sphinx.application.Sphinx.add_css_file()`
* - ``sphinx.application.Sphinx.override_domain()``
- 1.8
- 3.0

52
sphinx/application.py
View File

@ -27,7 +27,9 @@ from six.moves import cStringIO
import sphinx
from sphinx import package_dir, locale
from sphinx.config import Config
from sphinx.deprecation import RemovedInSphinx20Warning, RemovedInSphinx30Warning
from sphinx.deprecation import (
RemovedInSphinx20Warning, RemovedInSphinx30Warning, RemovedInSphinx40Warning
)
from sphinx.environment import BuildEnvironment
from sphinx.errors import (
ApplicationError, ConfigError, ExtensionError, VersionRequirementError
@ -1001,13 +1003,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_css_file(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_css_file('custom.css')
# => <link rel="stylesheet" href="_static/custom.css" type="text/css" />
app.add_css_file('print.css', media='print')
# => <link rel="stylesheet" href="_static/print.css"
# type="text/css" media="print" />
app.add_css_file('fancy.css', rel='alternate stylesheet', title='fancy')
# => <link rel="alternate stylesheet" href="_static/fancy.css"
# type="text/css" title="fancy" />
.. versionadded:: 1.0
@ -1017,17 +1033,33 @@ 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
Renamed from ``app.add_stylesheet()``.
And it 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)
self.registry.add_css_files(filename, **kwargs)
def add_stylesheet(self, filename, alternate=False, title=None):
# type: (unicode, bool, unicode) -> None
"""An alias of :meth:`add_css_file`."""
warnings.warn('The app.add_stylesheet() is deprecated. '
'Please use app.add_css_file() instead.',
RemovedInSphinx40Warning)
attributes = {} # type: Dict[unicode, unicode]
if alternate:
rel = u'alternate stylesheet'
attributes['rel'] = 'alternate stylesheet'
else:
rel = u'stylesheet'
css = Stylesheet(filename, title, rel) # type: ignore
StandaloneHTMLBuilder.css_files.append(css)
attributes['rel'] = 'stylesheet'
if title:
attributes['title'] = title
self.add_css_file(filename, **attributes)
def add_latex_package(self, packagename, options=None):
# type: (unicode, unicode) -> None

1
sphinx/builders/epub3.py
View File

@ -247,6 +247,7 @@ def setup(app):
app.add_config_value('epub_guide', (), 'env')
app.add_config_value('epub_pre_files', [], 'env')
app.add_config_value('epub_post_files', [], 'env')
app.add_config_value('epub_css_files', lambda config: config.html_css_files, 'epub')
app.add_config_value('epub_exclude_files', [], 'env')
app.add_config_value('epub_tocdepth', 3, 'env')
app.add_config_value('epub_tocdup', True, 'env')

62
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,19 @@ 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')
self.attributes.setdefault('type', 'text/css')
if args: # old style arguments (rel, title)
self.attributes['rel'] = args[0]
self.attributes['title'] = args[1]
return self
@ -241,8 +249,6 @@ class StandaloneHTMLBuilder(Builder):
# This is a class attribute because it is mutated by Sphinx.add_javascript.
script_files = ['_static/jquery.js', '_static/underscore.js',
'_static/doctools.js'] # type: List[unicode]
# Ditto for this one (Sphinx.add_stylesheet).
css_files = CSSContainer() # type: List[Dict[unicode, unicode]]
imgpath = None # type: unicode
domain_indices = [] # type: List[Tuple[unicode, Type[Index], List[Tuple[unicode, List[List[Union[unicode, int]]]]], bool]] # NOQA
@ -250,6 +256,13 @@ class StandaloneHTMLBuilder(Builder):
# cached publisher object for snippets
_publisher = None
def __init__(self, app):
# type: (Sphinx) -> None
super(StandaloneHTMLBuilder, self).__init__(app)
# CSS files
self.css_files = CSSContainer() # type: List[Dict[unicode, unicode]]
def init(self):
# type: () -> None
self.build_info = self.create_build_info()
@ -262,6 +275,7 @@ class StandaloneHTMLBuilder(Builder):
self.init_templates()
self.init_highlighter()
self.init_css_files()
if self.config.html_file_suffix is not None:
self.out_suffix = self.config.html_file_suffix
@ -324,6 +338,27 @@ class StandaloneHTMLBuilder(Builder):
self.highlighter = PygmentsBridge('html', style,
self.config.trim_doctest_flags)
def init_css_files(self):
# type: () -> None
for filename, attrs in self.app.registry.css_files:
self.css_files.append(Stylesheet(filename, **attrs)) # type: ignore
for entry in self.get_builder_config('css_files', 'html'):
if isinstance(entry, string_types):
filename = entry
attrs = {}
else:
try:
filename, attrs = entry
except (TypeError, ValueError):
logger.warning('invalid css_file: %r', entry)
continue
if '://' not in filename:
filename = path.join('_static', filename)
self.css_files.append(Stylesheet(filename, **attrs)) # type: ignore
@property
def default_translator_class(self):
# type: () -> nodes.NodeVisitor
@ -988,6 +1023,17 @@ class StandaloneHTMLBuilder(Builder):
return uri
ctx['pathto'] = pathto
def css_tag(css):
# type: (Stylesheet) -> unicode
attrs = []
for key in sorted(css.attributes):
value = css.attributes[key]
if value is not None:
attrs.append('%s="%s"' % (key, htmlescape(value, True)))
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:
@ -1316,6 +1362,7 @@ class SerializingHTMLBuilder(StandaloneHTMLBuilder):
self.templates = None # no template bridge necessary
self.init_templates()
self.init_highlighter()
self.init_css_files()
self.use_index = self.get_builder_config('use_index', 'html')
def get_target_uri(self, docname, typ=None):
@ -1440,6 +1487,7 @@ def setup(app):
app.add_config_value('html_style', None, 'html', string_classes)
app.add_config_value('html_logo', None, 'html', string_classes)
app.add_config_value('html_favicon', None, 'html', string_classes)
app.add_config_value('html_css_files', [], 'html')
app.add_config_value('html_static_path', [], 'html')
app.add_config_value('html_extra_path', [], 'html')
app.add_config_value('html_last_updated_fmt', None, 'html', string_classes)

4
sphinx/deprecation.py
View File

@ -33,6 +33,10 @@ class RemovedInSphinx30Warning(PendingDeprecationWarning):
pass
class RemovedInSphinx40Warning(PendingDeprecationWarning):
pass
RemovedInNextVersionWarning = RemovedInSphinx18Warning

6
sphinx/registry.py
View File

@ -65,6 +65,9 @@ class SphinxComponentRegistry(object):
#: autodoc documenters; a dict of documenter name -> documenter class
self.documenters = {} # type: Dict[unicode, Type[Documenter]]
#: css_files; a list of tuple of filename and attributes
self.css_files = [] # type: List[Tuple[unicode, Dict[unicode, unicode]]]
#: domains; a dict of domain name -> domain class
self.domains = {} # type: Dict[unicode, Type[Domain]]
@ -412,6 +415,9 @@ class SphinxComponentRegistry(object):
# type: (Type, Callable[[Any, unicode, Any], Any]) -> None
self.autodoc_attrgettrs[typ] = attrgetter
def add_css_files(self, filename, **attributes):
self.css_files.append((filename, attributes))
def add_latex_package(self, name, options):
# type: (unicode, unicode) -> None
logger.debug('[app] adding latex package: %r', name)

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 %}

2
tests/roots/test-html_assets/conf.py
View File

@ -6,4 +6,6 @@ version = '1.4.4'
html_static_path = ['static', 'subdir']
html_extra_path = ['extra', 'subdir']
html_css_files = ['css/style.css',
('https://example.com/custom.css', {'title': 'title', 'media': 'print'})]
exclude_patterns = ['**/_build', '**/.htpasswd']

0
tests/roots/test-html_assets/static/js/custom.js Normal file
View File

28
tests/test_build_epub.py
View File

@ -317,6 +317,34 @@ def test_epub_writing_mode(app):
assert 'writing-mode: vertical-rl;' in css
@pytest.mark.sphinx('epub', testroot='html_assets')
def test_epub_assets(app):
app.builder.build_all()
# epub_sytlesheets (same as html_css_files)
content = (app.outdir / 'index.xhtml').text()
assert ('<link rel="stylesheet" type="text/css" href="_static/css/style.css" />'
in content)
assert ('<link media="print" rel="stylesheet" title="title" type="text/css" '
'href="https://example.com/custom.css" />' in content)
@pytest.mark.sphinx('epub', testroot='html_assets',
confoverrides={'epub_css_files': ['css/epub.css']})
def test_epub_css_files(app):
app.builder.build_all()
# epub_css_files
content = (app.outdir / 'index.xhtml').text()
assert '<link rel="stylesheet" type="text/css" href="_static/css/epub.css" />' in content
# files in html_css_files are not outputed
assert ('<link rel="stylesheet" type="text/css" href="_static/css/style.css" />'
not in content)
assert ('<link media="print" rel="stylesheet" title="title" type="text/css" '
'href="https://example.com/custom.css" />' not in content)
@pytest.mark.sphinx('epub')
def test_run_epubcheck(app):
app.build()

13
tests/test_build_html.py
View File

@ -1094,9 +1094,10 @@ def test_html_assets(app):
assert not (app.outdir / '_static' / '.htpasswd').exists()
assert (app.outdir / '_static' / 'API.html').exists()
assert (app.outdir / '_static' / 'API.html').text() == 'Sphinx-1.4.4'
assert (app.outdir / '_static' / 'css/style.css').exists()
assert (app.outdir / '_static' / 'css' / 'style.css').exists()
assert (app.outdir / '_static' / 'js' / 'custom.js').exists()
assert (app.outdir / '_static' / 'rimg.png').exists()
assert not (app.outdir / '_static' / '_build/index.html').exists()
assert not (app.outdir / '_static' / '_build' / 'index.html').exists()
assert (app.outdir / '_static' / 'background.png').exists()
assert not (app.outdir / '_static' / 'subdir' / '.htaccess').exists()
assert not (app.outdir / '_static' / 'subdir' / '.htpasswd').exists()
@ -1107,11 +1108,17 @@ def test_html_assets(app):
assert (app.outdir / 'API.html_t').exists()
assert (app.outdir / 'css/style.css').exists()
assert (app.outdir / 'rimg.png').exists()
assert not (app.outdir / '_build/index.html').exists()
assert not (app.outdir / '_build' / 'index.html').exists()
assert (app.outdir / 'background.png').exists()
assert (app.outdir / 'subdir' / '.htaccess').exists()
assert not (app.outdir / 'subdir' / '.htpasswd').exists()
# html_css_files
content = (app.outdir / 'index.html').text()
assert '<link rel="stylesheet" type="text/css" href="_static/css/style.css" />' in content
assert ('<link media="print" rel="stylesheet" title="title" type="text/css" '
'href="https://example.com/custom.css" />' in content)
@pytest.mark.sphinx('html', testroot='basic', confoverrides={'html_copy_source': False})
def test_html_copy_source(app):