add preliminary API docs

docs/source/api/auth.rst

@@ -0,0 +1,21 @@
+==============
+Authenticators
+==============
+
+Module: :mod:`jupyterhub.auth`
+==============================
+
+.. automodule:: jupyterhub.auth
+
+.. currentmodule:: jupyterhub.auth
+
+
+
+.. autoclass:: Authenticator
+    :members:
+
+.. autoclass:: LocalAuthenticator
+    :members:
+
+.. autoclass:: PAMAuthenticator
+

docs/source/api/index.rst

@@ -0,0 +1,14 @@
+.. _api-index:
+
+####################
+ The JupyterHub API
+####################
+
+:Release: |release|
+:Date: |today|
+
+.. toctree::
+
+    auth
+    spawner
+    user

docs/source/api/spawner.rst

@@ -0,0 +1,18 @@
+==============
+   Spawners
+==============
+
+Module: :mod:`jupyterhub.spawner`
+=================================
+
+.. automodule:: jupyterhub.spawner
+
+.. currentmodule:: jupyterhub.spawner
+
+:class:`Spawner`
+----------------
+
+.. autoclass:: Spawner
+    :members: options_from_form, poll, start, stop, get_args, get_env, get_state
+
+.. autoclass:: LocalProcessSpawner

docs/source/api/user.rst

@@ -0,0 +1,31 @@
+=============
+   Users
+=============
+
+Module: :mod:`jupyterhub.user`
+==============================
+
+.. automodule:: jupyterhub.user
+
+.. currentmodule:: jupyterhub.user
+
+:class:`User`
+-------------
+
+.. class:: Server
+
+.. autoclass:: User
+    :members: escaped_name
+    
+    .. attribute:: name
+    
+      The user's name
+    
+    .. attribute:: server
+    
+        The user's Server data object if running, None otherwise.
+        Has ``ip``, ``port`` attributes.
+
+    .. attribute:: spawner
+    
+        The user's :class:`~.Spawner` instance.

docs/source/conf.py

@@ -35,7 +35,7 @@ import recommonmark.parser
 extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.intersphinx',
-    'sphinx.ext.mathjax',
+    'sphinx.ext.napoleon',
 ]
 
 # Add any paths that contain templates here, relative to this directory.

docs/source/index.rst

@@ -46,6 +46,7 @@ Contents:
    :maxdepth: 1
    :caption: Developer Documentation
    
+   api/index
 
 
 .. toctree::

jupyterhub/auth.py

@@ -1,4 +1,4 @@
-"""Simple PAM authenticator"""
+"""Base Authenticator class and the default PAM Authenticator"""
 
 # Copyright (c) IPython Development Team.
 # Distributed under the terms of the Modified BSD License.
@@ -24,7 +24,8 @@ from .traitlets import Command
 class Authenticator(LoggingConfigurable):
     """A class for authentication.
     
-    The API is one method, `authenticate`, a tornado gen.coroutine.
+    The primary API is one method, `authenticate`, a tornado coroutine
+    for authenticating users.
     """
     
     db = Any()
@@ -145,6 +146,14 @@ class Authenticator(LoggingConfigurable):
         and return None on failed authentication.
         
         Checking the whitelist is handled separately by the caller.
+
+        Args:
+            handler (tornado.web.RequestHandler): the current request handler
+            data (dict): The formdata of the login form.
+                         The default form has 'username' and 'password' fields.
+        Return:
+            str: the username of the authenticated user
+            None: Authentication failed
         """
 
     def pre_spawn_start(self, user, spawner):
@@ -165,7 +174,11 @@ class Authenticator(LoggingConfigurable):
         By default, this just adds the user to the whitelist.
         
         Subclasses may do more extensive things,
-        such as adding actual unix users.
+        such as adding actual unix users,
+        but they should call super to ensure the whitelist is updated.
+
+        Args:
+            user (User): The User wrapper object
         """
         if not self.validate_username(user.name):
             raise ValueError("Invalid username: %s" % user.name)
@@ -176,21 +189,52 @@ class Authenticator(LoggingConfigurable):
         """Triggered when a user is deleted.
         
         Removes the user from the whitelist.
+        Subclasses should call super to ensure the whitelist is updated.
+        
+        Args:
+            user (User): The User wrapper object
         """
         self.whitelist.discard(user.name)
     
     def login_url(self, base_url):
-        """Override to register a custom login handler"""
+        """Override to register a custom login handler
+        
+        Generally used in combination with get_handlers.
+        
+        Args:
+            base_url (str): the base URL of the Hub (e.g. /hub/)
+        
+        Returns:
+            str: The login URL, e.g. '/hub/login'
+        
+        """
         return url_path_join(base_url, 'login')
     
     def logout_url(self, base_url):
-        """Override to register a custom logout handler"""
+        """Override to register a custom logout handler.
+        
+        Generally used in combination with get_handlers.
+        
+        Args:
+            base_url (str): the base URL of the Hub (e.g. /hub/)
+        
+        Returns:
+            str: The logout URL, e.g. '/hub/logout'
+        """
         return url_path_join(base_url, 'logout')
     
     def get_handlers(self, app):
         """Return any custom handlers the authenticator needs to register
         
-        (e.g. for OAuth)
+        (e.g. for OAuth).
+        
+        Args:
+            app (JupyterHub Application):
+                the application object, in case it needs to be accessed for info.
+        Returns:
+            list: list of ``('/url', Handler)`` tuples passed to tornado.
+                The Hub prefix is added to any URLs.
+        
         """
         return [
             ('/login', LoginHandler),

jupyterhub/spawner.py

@@ -163,7 +163,7 @@ class Spawner(LoggingConfigurable):
         """store the state necessary for load_state
         
         A black box of extra state for custom spawners.
-        Should call `super`.
+        Subclasses should call `super`.
         
         Returns
         -------
@@ -333,7 +333,12 @@ def set_user_setuid(username):
 
 
 class LocalProcessSpawner(Spawner):
-    """A Spawner that just uses Popen to start local processes."""
+    """A Spawner that just uses Popen to start local processes as users.
+    
+    Requires users to exist on the local system.
+    
+    This is the default spawner for JupyterHub.
+    """
     
     INTERRUPT_TIMEOUT = Integer(10, config=True,
         help="Seconds to wait for process to halt after SIGINT before proceeding to SIGTERM"