Do not include the builder class in the entry point

- use the entry point to load the extension module in the usual way
- update the documentation to reflect this change

doc/extdev/builderapi.rst

@@ -11,6 +11,12 @@ Builder API
 
    This is the base class for all builders.
 
+   These attributes should be set on builder classes:
+
+   .. autoattribute:: name
+   .. autoattribute:: format
+   .. autoattribute:: supported_image_types
+
    These methods are predefined and will be called from the application:
 
    .. automethod:: get_relative_uri

doc/extdev/index.rst

@@ -28,25 +28,27 @@ Discovery of builders by entry point
 .. versionadded:: 1.6
 
 :term:`Builder` extensions can be discovered by means of `entry points`_ so
-they do not have to be listed in the :confval:`extensions` configuration value.
+that they do not have to be listed in the :confval:`extensions` configuration
+value.
 
-Builder extensions need to define an entry point in the ``sphinx.builders``
+Builder extensions should define an entry point in the ``sphinx.builders``
-group. The name of the entry point needs to be set to the name of the builder,
+group. The name of the entry point needs to match your builder's
-which is the name passed to the :option:`sphinx-build -b` option. Here is an
+:attr:`~.Builder.name` attribute, which is the name passed to the
-example of how an entry point for 'mybuilder' can be defined in ``setup.py``::
+:option:`sphinx-build -b` option. The entry point value should equal the
+dotted name of the extension module. Here is an example of how an entry point
+for 'mybuilder' can be defined in the extension's ``setup.py``::
 
     setup(
         # ...
         entry_points={
             'sphinx.builders': [
-                'mybuilder = mypackage.mymodule:MyBuilder',
+                'mybuilder = my.extension.module',
             ],
         }
     )
 
-It is no longer strictly necessary to register the builder using
+Note that it is still necessary to register the builder using
-:meth:`~.Sphinx.add_builder` in the extension's ``setup()`` function, but it is
+:meth:`~.Sphinx.add_builder` in the extension's :func:`setup` function.
-recommended to not remove this in order to ensure backward compatiblity.
 
 .. _entry points: https://setuptools.readthedocs.io/en/latest/setuptools.html#dynamic-discovery-of-services-and-plugins
 

sphinx/application.py

@@ -299,18 +299,15 @@ class Sphinx(object):
         if buildername is None:
             logger.info(_('No builder selected, using default: html'))
             buildername = 'html'
-        if buildername in self.builderclasses:
+        if buildername not in self.builderclasses:
-            builderclass = self.builderclasses[buildername]
-        else:
             entry_points = iter_entry_points('sphinx.builders', buildername)
             try:
                 entry_point = next(entry_points)
             except StopIteration:
                 raise SphinxError('Builder name %s not registered or available'
                                   ' through entry point' % buildername)
-            else:
+            load_extension(self, entry_point.module_name)
-                builderclass = entry_point.load()
+        builderclass = self.builderclasses[buildername]
-                load_extension(self, builderclass.__module__)
         return builderclass(self)
 
     def _init_builder(self):

sphinx/builders/__init__.py

@@ -49,9 +49,9 @@ class Builder(object):
     Builds target formats from the reST sources.
     """
 
-    # builder's name, for the -b command line options
+    #: The builder's name, for the -b command line option.
     name = ''  # type: unicode
-    # builder's output format, or '' if no document output is produced
+    #: The builder's output format, or '' if no document output is produced.
     format = ''  # type: unicode
     # doctree versioning method
     versioning_method = 'none'  # type: unicode
@@ -157,6 +157,8 @@ class Builder(object):
         """Return list of paths for assets (ex. templates, CSS, etc.)."""
         return []
 
+    #: The list of MIME types of image formats supported by the builder.
+    #: Image files are searched in the order in which they appear here.
     supported_image_types = []  # type: List[unicode]
 
     def post_process_images(self, doctree):