sphinx/tests/test_theming.py

"""Test the Theme class."""

import os

import alabaster
import pytest

import sphinx.builders.html
from sphinx.theming import ThemeError


@pytest.mark.sphinx(
    testroot='theming',
    confoverrides={'html_theme': 'ziptheme',
                   'html_theme_options.testopt': 'foo'})
def test_theme_api(app, status, warning):
    cfg = app.config

    themes = ['basic', 'default', 'scrolls', 'agogo', 'sphinxdoc', 'haiku',
              'traditional', 'epub', 'nature', 'pyramid', 'bizstyle', 'classic', 'nonav',
              'test-theme', 'ziptheme', 'staticfiles', 'parent', 'child']
    try:
        alabaster_version = alabaster.__version_info__
    except AttributeError:
        alabaster_version = alabaster.version.__version_info__
    if alabaster_version >= (0, 7, 11):
        themes.append('alabaster')

    # test Theme class API
    assert set(app.registry.html_themes.keys()) == set(themes)
    assert app.registry.html_themes['test-theme'] == str(app.srcdir / 'test_theme' / 'test-theme')
    assert app.registry.html_themes['ziptheme'] == str(app.srcdir / 'ziptheme.zip')
    assert app.registry.html_themes['staticfiles'] == str(app.srcdir / 'test_theme' / 'staticfiles')

    # test Theme instance API
    theme = app.builder.theme
    assert theme.name == 'ziptheme'
    themedir = theme.themedir
    assert theme.base.name == 'basic'
    assert len(theme.get_theme_dirs()) == 2

    # direct setting
    assert theme.get_config('theme', 'stylesheet') == 'custom.css'
    # inherited setting
    assert theme.get_config('options', 'nosidebar') == 'false'
    # nonexisting setting
    assert theme.get_config('theme', 'foobar', 'def') == 'def'
    with pytest.raises(ThemeError):
        theme.get_config('theme', 'foobar')

    # options API

    options = theme.get_options({'nonexisting': 'foo'})
    assert 'nonexisting' not in options.keys()

    options = theme.get_options(cfg.html_theme_options)
    assert options['testopt'] == 'foo'
    assert options['nosidebar'] == 'false'

    # cleanup temp directories
    theme.cleanup()
    assert not os.path.exists(themedir)


@pytest.mark.sphinx(testroot='double-inheriting-theme')
def test_double_inheriting_theme(app, status, warning):
    assert app.builder.theme.name == 'base_theme2'
    app.build()  # => not raises TemplateNotFound


@pytest.mark.sphinx(testroot='theming',
                    confoverrides={'html_theme': 'child'})
def test_nested_zipped_theme(app, status, warning):
    assert app.builder.theme.name == 'child'
    app.build()  # => not raises TemplateNotFound


@pytest.mark.sphinx(testroot='theming',
                    confoverrides={'html_theme': 'staticfiles'})
def test_staticfiles(app, status, warning):
    app.build()
    assert (app.outdir / '_static' / 'staticimg.png').exists()
    assert (app.outdir / '_static' / 'statictmpl.html').exists()
    assert (app.outdir / '_static' / 'statictmpl.html').read_text(encoding='utf8') == (
        '<!-- testing static templates -->\n'
        '<html><project>Python</project></html>'
    )

    result = (app.outdir / 'index.html').read_text(encoding='utf8')
    assert '<meta name="testopt" content="optdefault" />' in result


@pytest.mark.sphinx(testroot='theming',
                    confoverrides={'html_theme': 'test-theme'})
def test_dark_style(app, monkeypatch):
    monkeypatch.setattr(sphinx.builders.html, '_file_checksum', lambda o, f: '')

    style = app.builder.dark_highlighter.formatter_args.get('style')
    assert style.__name__ == 'MonokaiStyle'

    app.build()
    assert (app.outdir / '_static' / 'pygments_dark.css').exists()

    css_file, properties = app.registry.css_files[0]
    assert css_file == 'pygments_dark.css'
    assert "media" in properties
    assert properties["media"] == '(prefers-color-scheme: dark)'

    assert sorted(f.filename for f in app.builder._css_files) == [
        '_static/classic.css',
        '_static/pygments.css',
        '_static/pygments_dark.css',
    ]

    result = (app.outdir / 'index.html').read_text(encoding='utf8')
    assert '<link rel="stylesheet" type="text/css" href="_static/pygments.css" />' in result
    assert ('<link id="pygments_dark_css" media="(prefers-color-scheme: dark)" '
            'rel="stylesheet" type="text/css" '
            'href="_static/pygments_dark.css" />') in result


@pytest.mark.sphinx(testroot='theming')
def test_theme_sidebars(app, status, warning):
    app.build()

    # test-theme specifies globaltoc and searchbox as default sidebars
    result = (app.outdir / 'index.html').read_text(encoding='utf8')
    assert '<h3><a href="#">Table of Contents</a></h3>' in result
    assert '<h3>Related Topics</h3>' not in result
    assert '<h3>This Page</h3>' not in result
    assert '<h3 id="searchlabel">Quick search</h3>' in result
Collapse single line docstrings 2022-02-19 21:05:56 -06:00			`"""Test the Theme class."""`
Add theming test suite, fix a few bugs and doc problems. 2009-02-15 09:10:10 -06:00
			`import os`

Fix broken testcase by alabaster-0.711 2018-06-19 07:58:06 -05:00			`import alabaster`
Fix tests 2020-03-14 13:46:37 -05:00			`import pytest`
Sort imports with isort Keep imports alphabetically sorted and their order homogeneous across Python source files. The isort project has more feature and is more active than the flake8-import-order plugin. Most issues caught were simply import ordering from the same module. Where imports were purposefully placed out of order, tag with isort:skip. 2020-11-11 05:00:27 -06:00
Fix ``test_dark_style`` for Pygments 2.16 2023-08-07 15:02:25 -05:00			`import sphinx.builders.html`
Add HTMLThemeFactory class 2017-04-20 06:19:55 -05:00			`from sphinx.theming import ThemeError`
refs #1777: add test for loading theme plugins 2015-03-14 10:47:43 -05:00

pytest: remove deprecated with_app decorator functions 2017-01-05 10:14:47 -06:00			`@pytest.mark.sphinx(`
diet test-root: Move ziptheme to test-theming 2017-12-13 08:48:07 -06:00			`testroot='theming',`
pytest: remove deprecated with_app decorator functions 2017-01-05 10:14:47 -06:00			`confoverrides={'html_theme': 'ziptheme',`
			`'html_theme_options.testopt': 'foo'})`
Complete test suite overhaul. * rename a few test modules to make the names more consistent * do not copy/use Sphinx from build/ (unnecessary without 2to3) * use a temporary dir for all test projects, the source tree will stay pristine that way (default is tests/build) * speed up tests by ~3x by splitting up test projects and avoiding rebuilds 2014-09-21 10:17:02 -05:00			`def test_theme_api(app, status, warning):`
Add theming test suite, fix a few bugs and doc problems. 2009-02-15 09:10:10 -06:00			`cfg = app.config`

Fix broken testcase by alabaster-0.711 2018-06-19 07:58:06 -05:00			`themes = ['basic', 'default', 'scrolls', 'agogo', 'sphinxdoc', 'haiku',`
			`'traditional', 'epub', 'nature', 'pyramid', 'bizstyle', 'classic', 'nonav',`
			`'test-theme', 'ziptheme', 'staticfiles', 'parent', 'child']`
Update test for Alabaster version tuple 2023-04-26 11:04:48 -05:00			`try:`
			`alabaster_version = alabaster.__version_info__`
			`except AttributeError:`
			`alabaster_version = alabaster.version.__version_info__`
			`if alabaster_version >= (0, 7, 11):`
Fix broken testcase by alabaster-0.711 2018-06-19 07:58:06 -05:00			`themes.append('alabaster')`

Add theming test suite, fix a few bugs and doc problems. 2009-02-15 09:10:10 -06:00			`# test Theme class API`
refactor: app.html_themes was replaced by registry.html_themes 2021-12-10 19:52:22 -06:00			`assert set(app.registry.html_themes.keys()) == set(themes)`
Start using ``pathlib.Path`` and deprecate ``sphinx.testing.path`` (#11526) 2023-07-27 18:39:12 -05:00			`assert app.registry.html_themes['test-theme'] == str(app.srcdir / 'test_theme' / 'test-theme')`
			`assert app.registry.html_themes['ziptheme'] == str(app.srcdir / 'ziptheme.zip')`
			`assert app.registry.html_themes['staticfiles'] == str(app.srcdir / 'test_theme' / 'staticfiles')`
Add theming test suite, fix a few bugs and doc problems. 2009-02-15 09:10:10 -06:00
			`# test Theme instance API`
			`theme = app.builder.theme`
			`assert theme.name == 'ziptheme'`
			`themedir = theme.themedir`
			`assert theme.base.name == 'basic'`
Drop old methods 2017-04-20 09:38:48 -05:00			`assert len(theme.get_theme_dirs()) == 2`
Add theming test suite, fix a few bugs and doc problems. 2009-02-15 09:10:10 -06:00
			`# direct setting`
Drop old methods 2017-04-20 09:38:48 -05:00			`assert theme.get_config('theme', 'stylesheet') == 'custom.css'`
Add theming test suite, fix a few bugs and doc problems. 2009-02-15 09:10:10 -06:00			`# inherited setting`
Drop old methods 2017-04-20 09:38:48 -05:00			`assert theme.get_config('options', 'nosidebar') == 'false'`
Add theming test suite, fix a few bugs and doc problems. 2009-02-15 09:10:10 -06:00			`# nonexisting setting`
Drop old methods 2017-04-20 09:38:48 -05:00			`assert theme.get_config('theme', 'foobar', 'def') == 'def'`
pytest: remove deprecated raises and raises_msg assert functions 2017-01-05 09:46:42 -06:00			`with pytest.raises(ThemeError):`
Drop old methods 2017-04-20 09:38:48 -05:00			`theme.get_config('theme', 'foobar')`
Add theming test suite, fix a few bugs and doc problems. 2009-02-15 09:10:10 -06:00
			`# options API`
Changed test case "test_theme_api" to check, if a not needed html_theme_option is not part of the returned, final configuration of theme.get_options(). PR #3893 2017-06-26 02:17:08 -05:00
			`options = theme.get_options({'nonexisting': 'foo'})`
			`assert 'nonexisting' not in options.keys()`

Add theming test suite, fix a few bugs and doc problems. 2009-02-15 09:10:10 -06:00			`options = theme.get_options(cfg.html_theme_options)`
			`assert options['testopt'] == 'foo'`
			`assert options['nosidebar'] == 'false'`

			`# cleanup temp directories`
			`theme.cleanup()`
			`assert not os.path.exists(themedir)`
* Provide non-minified JS files for jquery.js and underscore.js to clarify the source of the minified files. refs #1434. 2014-06-07 04:32:56 -05:00
Complete test suite overhaul. * rename a few test modules to make the names more consistent * do not copy/use Sphinx from build/ (unnecessary without 2to3) * use a temporary dir for all test projects, the source tree will stay pristine that way (default is tests/build) * speed up tests by ~3x by splitting up test projects and avoiding rebuilds 2014-09-21 10:17:02 -05:00
pytest: remove deprecated with_app decorator functions 2017-01-05 10:14:47 -06:00			`@pytest.mark.sphinx(testroot='double-inheriting-theme')`
Refactor sphinx.theming 2017-04-20 00:04:49 -05:00			`def test_double_inheriting_theme(app, status, warning):`
			`assert app.builder.theme.name == 'base_theme2'`
			`app.build() # => not raises TemplateNotFound`
Fix fail to load template file if the parent template is archived 2017-04-18 09:22:03 -05:00

			`@pytest.mark.sphinx(testroot='theming',`
			`confoverrides={'html_theme': 'child'})`
			`def test_nested_zipped_theme(app, status, warning):`
Refactor sphinx.theming 2017-04-20 00:04:49 -05:00			`assert app.builder.theme.name == 'child'`
Fix fail to load template file if the parent template is archived 2017-04-18 09:22:03 -05:00			`app.build() # => not raises TemplateNotFound`
HTML themes can set up default sidebars through ``theme.conf`` 2017-10-22 01:12:31 -05:00

diet test-root: Move testtheme to test-theming 2017-12-13 08:48:07 -06:00			`@pytest.mark.sphinx(testroot='theming',`
			`confoverrides={'html_theme': 'staticfiles'})`
			`def test_staticfiles(app, status, warning):`
			`app.build()`
			`assert (app.outdir / '_static' / 'staticimg.png').exists()`
			`assert (app.outdir / '_static' / 'statictmpl.html').exists()`
`.read_text()` -> `.read_text(encoding='utf8')` 2022-04-26 21:04:19 -05:00			`assert (app.outdir / '_static' / 'statictmpl.html').read_text(encoding='utf8') == (`
diet test-root: Move testtheme to test-theming 2017-12-13 08:48:07 -06:00			`'<!-- testing static templates -->\n'`
			`'<html><project>Python</project></html>'`
			`)`

`.read_text()` -> `.read_text(encoding='utf8')` 2022-04-26 21:04:19 -05:00			`result = (app.outdir / 'index.html').read_text(encoding='utf8')`
diet test-root: Move testtheme to test-theming 2017-12-13 08:48:07 -06:00			`assert '<meta name="testopt" content="optdefault" />' in result`
Merge branch 'stable' 2017-12-15 09:53:55 -06:00

Remove html_pygments_dark_style option 2020-03-14 12:46:02 -05:00			`@pytest.mark.sphinx(testroot='theming',`
			`confoverrides={'html_theme': 'test-theme'})`
Fix ``test_dark_style`` for Pygments 2.16 2023-08-07 15:02:25 -05:00			`def test_dark_style(app, monkeypatch):`
			`monkeypatch.setattr(sphinx.builders.html, '_file_checksum', lambda o, f: '')`

Fix checking wrong highlighter 2020-03-14 12:49:25 -05:00			`style = app.builder.dark_highlighter.formatter_args.get('style')`
Remove html_pygments_dark_style option 2020-03-14 12:46:02 -05:00			`assert style.__name__ == 'MonokaiStyle'`

			`app.build()`
			`assert (app.outdir / '_static' / 'pygments_dark.css').exists()`

Fix ``test_dark_style`` for Pygments 2.16 2023-08-07 15:02:25 -05:00			`css_file, properties = app.registry.css_files[0]`
			`assert css_file == 'pygments_dark.css'`
			`assert "media" in properties`
			`assert properties["media"] == '(prefers-color-scheme: dark)'`

Deprecate ``css_files`` and ``script_files`` (#11582) 2023-08-11 19:46:44 -05:00			`assert sorted(f.filename for f in app.builder._css_files) == [`
Fix ``test_dark_style`` for Pygments 2.16 2023-08-07 15:02:25 -05:00			`'_static/classic.css',`
			`'_static/pygments.css',`
			`'_static/pygments_dark.css',`
			`]`

`.read_text()` -> `.read_text(encoding='utf8')` 2022-04-26 21:04:19 -05:00			`result = (app.outdir / 'index.html').read_text(encoding='utf8')`
Fix ``test_dark_style`` for Pygments 2.16 2023-08-07 15:02:25 -05:00			`assert '<link rel="stylesheet" type="text/css" href="_static/pygments.css" />' in result`
Fix tests 2020-03-14 13:46:37 -05:00			`assert ('<link id="pygments_dark_css" media="(prefers-color-scheme: dark)" '`
			`'rel="stylesheet" type="text/css" '`
Fix ``test_dark_style`` for Pygments 2.16 2023-08-07 15:02:25 -05:00			`'href="_static/pygments_dark.css" />') in result`
Remove html_pygments_dark_style option 2020-03-14 12:46:02 -05:00

HTML themes can set up default sidebars through ``theme.conf`` 2017-10-22 01:12:31 -05:00			`@pytest.mark.sphinx(testroot='theming')`
			`def test_theme_sidebars(app, status, warning):`
			`app.build()`

			`# test-theme specifies globaltoc and searchbox as default sidebars`
`.read_text()` -> `.read_text(encoding='utf8')` 2022-04-26 21:04:19 -05:00			`result = (app.outdir / 'index.html').read_text(encoding='utf8')`
Capitalization: "Table Of Contents" -> "Table of Contents". This is consistent with "Complete Table of Contents" (which is already in the database), as well as e.g. "Indices and Tables" where "and" is not capitalized. This is also fairly standard title-case practice. 2018-07-21 16:13:16 -05:00			`assert '<h3><a href="#">Table of Contents</a></h3>' in result`
HTML themes can set up default sidebars through ``theme.conf`` 2017-10-22 01:12:31 -05:00			`assert '<h3>Related Topics</h3>' not in result`
			`assert '<h3>This Page</h3>' not in result`
Add a label to search input for accessability purposes. 2019-04-22 05:55:32 -05:00			`assert '<h3 id="searchlabel">Quick search</h3>' in result`