diff options
| -rw-r--r-- | CHANGES | 2 | ||||
| -rw-r--r-- | doc/extdev/appapi.rst | 7 | ||||
| -rw-r--r-- | doc/theming.rst | 70 | ||||
| -rw-r--r-- | sphinx/application.py | 5 | ||||
| -rw-r--r-- | sphinx/theming.py | 22 |
5 files changed, 78 insertions, 28 deletions
@@ -162,6 +162,8 @@ Deprecated removed at 1.7, and already its default value has changed from ``True`` to ``False``. * #3221: epub2 builder is deprecated +* #3628: ``sphinx_themes`` entry_point is deprecated. Please use + ``sphinx.html_themes`` instead. Release 1.5.6 (in development) ============================== diff --git a/doc/extdev/appapi.rst b/doc/extdev/appapi.rst index 50b2af0f8..151bb2ed9 100644 --- a/doc/extdev/appapi.rst +++ b/doc/extdev/appapi.rst @@ -370,6 +370,13 @@ package. .. versionadded:: 1.4 +.. method:: Sphinx.add_html_theme(name, theme_path) + + Register a HTML Theme. The *name* is a name of theme, and *path* is a + full path to the theme (refs: :ref:`distribute-your-theme`). + + .. versionadded:: 1.6 + .. method:: Sphinx.add_env_collector(collector) Register an environment collector class (refs: :ref:`collector-api`) diff --git a/doc/theming.rst b/doc/theming.rst index 1d895ec19..1236a85bf 100644 --- a/doc/theming.rst +++ b/doc/theming.rst @@ -46,34 +46,14 @@ file :file:`blue.zip`, you can put it right in the directory containing html_theme = "blue" html_theme_path = ["."] -The third form provides your theme path dynamically to Sphinx if the -``setuptools`` package is installed. You can provide an entry point section -called ``sphinx_themes`` in your setup.py file and write a ``get_path`` function -that has to return the directory with themes in it:: +The third form is a python package. If a theme you want to use is distributed +as a python package, you can use it after installing:: - # 'setup.py' + # installing theme package + $ pip install sphinxjp.themes.dotted - setup( - ... - entry_points = { - 'sphinx_themes': [ - 'path = your_package:get_path', - ] - }, - ... - ) - - # 'your_package.py' - - from os import path - package_dir = path.abspath(path.dirname(__file__)) - template_path = path.join(package_dir, 'themes') - - def get_path(): - return template_path - -.. versionadded:: 1.2 - 'sphinx_themes' entry_points feature. + # use it in your conf.py + html_theme = "dotted" .. _builtin-themes: @@ -310,6 +290,44 @@ Python :mod:`ConfigParser` module) and has the following structure: and are accessible from all templates as ``theme_<name>``. +.. _distribute-your-theme: + +Distribute your theme as a python package +----------------------------------------- + +As a way to distribute your theme, you can use python package. Python package +brings to users easy setting up ways. + +To distribute your theme as a python package, please define an entry point +called ``sphinx.html_themes`` in your setup.py file, and write a ``setup()`` +function to register your themes in it:: + + # 'setup.py' + setup( + ... + entry_points = { + 'sphinx.html_themes': [ + 'name_of_theme = your_package', + ] + }, + ... + ) + + # 'your_package.py' + from os import path + + def setup(app): + app.add_html_theme('name_of_theme', path.abspath(path.dirname(__file__))) + +.. versionadded:: 1.2 + 'sphinx_themes' entry_points feature. + +.. deprecated:: 1.6 + ``sphinx_themes`` entry_points has been deprecated. + +.. versionadded:: 1.6 + ``sphinx.html_themes`` entry_points feature. + Templating ~~~~~~~~~~ diff --git a/sphinx/application.py b/sphinx/application.py index 26126fb9c..edac70a99 100644 --- a/sphinx/application.py +++ b/sphinx/application.py @@ -800,6 +800,11 @@ class Sphinx(object): logger.debug('[app] adding environment collector: %r', collector) collector().enable(self) + def add_html_theme(self, name, theme_path): + # type: (unicode, unicode) -> None + logger.debug('[app] adding HTML theme: %r, %r', name, theme_path) + self.html_themes[name] = theme_path + class TemplateBridge(object): """ diff --git a/sphinx/theming.py b/sphinx/theming.py index f0c7667d3..5e023e5a1 100644 --- a/sphinx/theming.py +++ b/sphinx/theming.py @@ -12,6 +12,7 @@ import os import shutil import tempfile +import warnings from os import path from zipfile import ZipFile @@ -20,7 +21,9 @@ from six import string_types, iteritems from six.moves import configparser from sphinx import package_dir +from sphinx.deprecation import RemovedInSphinx20Warning from sphinx.errors import ThemeError +from sphinx.extension import load_extension from sphinx.locale import _ from sphinx.util import logging from sphinx.util.osutil import ensuredir @@ -77,6 +80,8 @@ class Theme(object): try: inherit = self.config.get('theme', 'inherit') + except configparser.NoSectionError: + raise ThemeError(_('theme %r doesn\'t have "theme" setting') % name) except configparser.NoOptionError: raise ThemeError(_('theme %r doesn\'t have "inherit" setting') % name) @@ -161,7 +166,7 @@ class HTMLThemeFactory(object): def __init__(self, app): # type: (Sphinx) -> None - self.confdir = app.confdir + self.app = app self.themes = app.html_themes self.load_builtin_themes() if getattr(app.config, 'html_theme_path', None): @@ -178,7 +183,7 @@ class HTMLThemeFactory(object): # type: (unicode) -> None """Load additional themes placed at specified directories.""" for theme_path in theme_paths: - abs_theme_path = path.abspath(path.join(self.confdir, theme_path)) + abs_theme_path = path.abspath(path.join(self.app.confdir, theme_path)) themes = self.find_themes(abs_theme_path) for name, theme in iteritems(themes): self.themes[name] = theme @@ -215,6 +220,16 @@ class HTMLThemeFactory(object): Sphinx refers to ``sphinx_themes`` entry_points. """ + # look up for new styled entry_points at first + entry_points = pkg_resources.iter_entry_points('sphinx.html_themes', name) + try: + entry_point = next(entry_points) + load_extension(self.app, entry_point.module_name) + return + except StopIteration: + pass + + # look up for old styled entry_points for entry_point in pkg_resources.iter_entry_points('sphinx_themes'): target = entry_point.load() if callable(target): @@ -228,6 +243,9 @@ class HTMLThemeFactory(object): themes = self.find_themes(themedir) for entry, theme in iteritems(themes): if name == entry: + warnings.warn('``sphinx_themes`` entry point is now deprecated. ' + 'Please use ``sphinx.html_themes`` instead.', + RemovedInSphinx20Warning) self.themes[name] = theme def find_themes(self, theme_path): |