Fix #3628: Rename sphinx_themes entry point to sphinx.html_themes

CHANGES

@@ -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)
 ==============================

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`)

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
 ~~~~~~~~~~
 

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):
     """

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):