allow spawners and authenticators to register via entrypoints

jupyterhub.authenticators for authenticators, jupyterhub.spawners for spawners

This has the effect that authenticators and spawners can be selected by name instead of full import string (e.g. 'github' or 'dummy' or 'kubernetes')
and, perhaps more importantly, the autogenerated configuration file will include a section for each installed and registered class.

docs/source/reference/authenticators.md

@@ -68,7 +68,6 @@ Writing an Authenticator that looks up passwords in a dictionary
 requires only overriding this one method:
 
 ```python
-from tornado import gen
 from IPython.utils.traitlets import Dict
 from jupyterhub.auth import Authenticator
 
@@ -78,8 +77,7 @@ class DictionaryAuthenticator(Authenticator):
         help="""dict of username:password for authentication"""
     )
 
-    @gen.coroutine
-    def authenticate(self, handler, data):
+    async def authenticate(self, handler, data):
         if self.passwords.get(data['username']) == data['password']:
             return data['username']
 ```
@@ -136,6 +134,41 @@ See a list of custom Authenticators [on the wiki](https://github.com/jupyterhub/
 If you are interested in writing a custom authenticator, you can read
 [this tutorial](http://jupyterhub-tutorial.readthedocs.io/en/latest/authenticators.html).
 
+### Registering custom Authenticators via entry points
+
+As of JupyterHub 1.0, custom authenticators can register themselves via
+the `jupyterhub.authenticators` entry point metadata.
+To do this, in your `setup.py` add:
+
+```python
+setup(
+  ...
+  entry_points={
+    'jupyterhub.authenticators': [
+        'myservice = mypackage:MyAuthenticator',
+    ],
+  },
+)
+```
+
+If you have added this metadata to your package,
+users can select your authenticator with the configuration:
+
+```python
+c.JupyterHub.authenticator_class = 'myservice'
+```
+
+instead of the full
+
+```python
+c.JupyterHub.authenticator_class = 'mypackage:MyAuthenticator'
+```
+
+previously required.
+Additionally, configurable attributes for your spawner will
+appear in jupyterhub help output and auto-generated configuration files
+via `jupyterhub --generate-config`.
+
 
 ### Authentication state
 

docs/source/reference/spawners.md

@@ -10,6 +10,7 @@ and a custom Spawner needs to be able to take three actions:
 
 
 ## Examples
+
 Custom Spawners for JupyterHub can be found on the [JupyterHub wiki](https://github.com/jupyterhub/jupyterhub/wiki/Spawners).
 Some examples include:
 
@@ -174,6 +175,42 @@ When `Spawner.start` is called, this dictionary is accessible as `self.user_opti
 
 If you are interested in building a custom spawner, you can read [this tutorial](http://jupyterhub-tutorial.readthedocs.io/en/latest/spawners.html).
 
+### Registering custom Spawners via entry points
+
+As of JupyterHub 1.0, custom Spawners can register themselves via
+the `jupyterhub.spawners` entry point metadata.
+To do this, in your `setup.py` add:
+
+```python
+setup(
+  ...
+  entry_points={
+    'jupyterhub.spawners': [
+        'myservice = mypackage:MySpawner',
+    ],
+  },
+)
+```
+
+If you have added this metadata to your package,
+users can select your authenticator with the configuration:
+
+```python
+c.JupyterHub.spawner_class = 'myservice'
+```
+
+instead of the full
+
+```python
+c.JupyterHub.spawner_class = 'mypackage:MySpawner'
+```
+
+previously required.
+Additionally, configurable attributes for your spawner will
+appear in jupyterhub help output and auto-generated configuration files
+via `jupyterhub --generate-config`.
+
+
 ## Spawners, resource limits, and guarantees (Optional)
 
 Some spawners of the single-user notebook servers allow setting limits or