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 theming test suite, fix a few bugs and doc problems.

Browse Source
This commit is contained in:
Georg Brandl
2009-02-15 16:10:10 +01:00
parent f48c9a6595
commit c3e13cfa9a
14 changed files with 92 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files

11
doc/theming.rst
View File

@@ -97,6 +97,9 @@ Sphinx comes with a selection of themes to choose from:
* **sphinxdoc** -- The theme used for this documentation. It features a sidebar
on the right side. There are currently no options beyond *nosidebar*.
* **traditional** -- A theme resembling the old Python documentation. There are
currently no options beyond *nosidebar*.
Creating themes
---------------
@@ -151,10 +154,10 @@ searches for templates:
* Then, in the selected theme.
* Then, in its base theme, its base's base theme, etc.
From all of these levels, you can inherit templates from the lowernext level by
prefixing the template name with an exclamation mark in the ``extends`` tag, or
(in the case of theme templates) giving an explicit path, like
``basic/layout.html``.
When extending a template in the base theme with the same name, use the theme
name as an explicit directory: ``{% extends "basic/layout.html" %}``. From a
user ``templates_path`` template, you can still use the "exclamation mark"
syntax as described in the templating document.
Static templates

1
sphinx/config.py
View File

@@ -133,7 +133,6 @@ class Config(object):
config.setdefault(realvalname, {})[key] = value
else:
config[valname] = value
config.update(self.overrides)
for name in config:
if name in self.values:
self.__dict__[name] = config[name]

5
sphinx/jinja2glue.py
View File

@@ -40,6 +40,7 @@ class BuiltinTemplateLoader(TemplateBridge, jinja2.BaseLoader):
chain.extend(self.theme.themepath)
# prepend explicit template paths
self.templatepathlen = len(builder.config.templates_path)
if builder.config.templates_path:
chain[0:0] = [path.join(builder.confdir, tp)
for tp in builder.config.templates_path]
@@ -71,9 +72,9 @@ class BuiltinTemplateLoader(TemplateBridge, jinja2.BaseLoader):
def get_source(self, environment, template):
loaders = self.loaders
# exclamation mark starts search from base
# exclamation mark starts search from theme
if template.startswith('!'):
loaders = loaders[1:]
loaders = loaders[self.templatepathlen:]
template = template[1:]
for loader in loaders:
try:

2
sphinx/theming.py
View File

@@ -110,7 +110,7 @@ class Theme(object):
return self.themeconf.get(section, name)
except (ConfigParser.NoOptionError, ConfigParser.NoSectionError):
if self.base is not None:
return self.base.get_confstr(section, name)
return self.base.get_confstr(section, name, default)
if default is NODEFAULT:
raise ThemeError('setting %s.%s occurs in none of the '
'searched theme configs' % (section, name))

1
tests/root/_templates/layout.html
View File

@@ -1,4 +1,5 @@
{% extends "!layout.html" %}
{% block extrahead %}
<meta name="hc" content="{{ hckey }}" />
{{ super() }}
{% endblock %}

4
tests/root/conf.py
View File

@@ -26,6 +26,10 @@ pygments_style = 'sphinx'
rst_epilog = '.. |subst| replace:: global substitution'
html_theme = 'testtheme'
html_theme_path = ['.']
html_theme_options = {'testopt': 'testoverride'}
html_style = 'default.css'
html_static_path = ['_static']
html_last_updated_fmt = '%b %d, %Y'

BIN
tests/root/rimg.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 66 KiB

After

Width:  |  Height:  |  Size: 218 B

5
tests/root/testtheme/layout.html Normal file
View File

@@ -0,0 +1,5 @@
{% extends "basic/layout.html" %}
{% block extrahead %}
<meta name="testopt" content="{{ theme_testopt }}" />
{{ super() }}
{% endblock %}

BIN
tests/root/testtheme/static/staticimg.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 218 B

2
tests/root/testtheme/static/statictmpl.html_t Normal file
View File

@@ -0,0 +1,2 @@
<!-- testing static templates -->
<html><project>{{ project|e }}</project></html>

7
tests/root/testtheme/theme.conf Normal file
View File

@@ -0,0 +1,7 @@
[theme]
inherit = basic
stylesheet = default.css
pygments_style = emacs
[options]
testopt = optdefault

BIN
tests/root/ziptheme.zip Normal file
View File

Binary file not shown.

6
tests/test_build.py
View File

@@ -89,6 +89,7 @@ HTML_XPATH = {
},
'contents.html': {
".//meta[@name='hc'][@content='hcval']": '',
".//meta[@name='testopt'][@content='testoverride']": '',
".//td[@class='label']": r'\[Ref1\]',
".//li[@class='toctree-l1']/a": 'Testing various markup',
".//li[@class='toctree-l2']/a": 'Admonitions',
@@ -96,6 +97,9 @@ HTML_XPATH = {
".//div[@class='footer']": 'Georg Brandl & Team',
".//a[@href='http://python.org/']": '',
},
'_static/statictmpl.html': {
".//project": 'Sphinx <Tests>',
},
}
if pygments:
@@ -141,6 +145,8 @@ def test_html(app):
etree = ET.parse(os.path.join(app.outdir, fname), parser)
for path, check in paths.iteritems():
nodes = list(etree.findall(path))
if not nodes:
import pdb; pdb.set_trace()
assert nodes != []
if hasattr(check, '__call__'):
check(nodes)

56
tests/test_theming.py Normal file
View File

@@ -0,0 +1,56 @@
# -*- coding: utf-8 -*-
"""
test_theming
~~~~~~~~~~~~
Test the Theme class.
:copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
import os
import zipfile
from util import *
from sphinx.theming import Theme, ThemeError
@with_app(confoverrides={'html_theme': 'ziptheme',
'html_theme_options.testopt': 'foo'})
def test_theme_api(app):
cfg = app.config
# test Theme class API
assert set(Theme.themes.keys()) == \
set(['basic', 'default', 'sphinxdoc', 'traditional',
'testtheme', 'ziptheme'])
assert Theme.themes['testtheme'][1] is None
assert isinstance(Theme.themes['ziptheme'][1], zipfile.ZipFile)
# test Theme instance API
theme = app.builder.theme
assert theme.name == 'ziptheme'
assert theme.themedir_created
themedir = theme.themedir
assert theme.base.name == 'basic'
assert len(theme.get_dirchain()) == 2
# direct setting
assert theme.get_confstr('theme', 'stylesheet') == 'custom.css'
# inherited setting
assert theme.get_confstr('options', 'nosidebar') == 'false'
# nonexisting setting
assert theme.get_confstr('theme', 'foobar', 'def') == 'def'
raises(ThemeError, theme.get_confstr, 'theme', 'foobar')
# options API
raises(ThemeError, theme.get_options, {'nonexisting': 'foo'})
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)