Merge pull request #1321 from willingc/doc-services

Add autodoc of services and update services.auth for OAuth

docs/environment.yml

@@ -4,6 +4,7 @@ channels:
 dependencies:
 - nodejs
 - python=3.5
+- alembic
 - jinja2
 - pamela
 - requests

docs/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jupyterhub-docs-build",
-  "version": "0.0.0",
+  "version": "0.8.0",
   "description": "build JupyterHub swagger docs",
   "scripts": {
     "rest-api": "bootprint openapi ./rest-api.yml source/_static/rest-api"
@@ -8,7 +8,7 @@
   "author": "",
   "license": "BSD-3-Clause",
   "devDependencies": {
-    "bootprint": "^0.10.0",
-    "bootprint-openapi": "^0.17.0"
+    "bootprint": "^1.0.0",
+    "bootprint-openapi": "^1.0.0"
   }
 }

docs/rest-api.yml

@@ -424,9 +424,6 @@ paths:
       responses:
         '200':
           description: The user or service identified by the API token
-          schema:
-            $ref: '#/definitions/User'
-            $ref: '#/definitions/Service'
         '404':
           description: A user or service is not found.
   /authorizations/cookie/{cookie_name}/{cookie_value}:

docs/source/api/app.rst

@@ -2,9 +2,15 @@
 Application configuration
 =========================
 
+Module: :mod:`jupyterhub.app`
+=============================
+
+.. automodule:: jupyterhub.app
+
 .. currentmodule:: jupyterhub.app
 
 :class:`JupyterHub`
 -------------------
 
 .. autoconfigurable:: JupyterHub
+

docs/source/api/auth.rst

@@ -9,13 +9,20 @@ Module: :mod:`jupyterhub.auth`
 
 .. currentmodule:: jupyterhub.auth
 
-
+:class:`Authenticator`
+----------------------
 
 .. autoconfigurable:: Authenticator
     :members:
 
+:class:`LocalAuthenticator`
+---------------------------
+
 .. autoconfigurable:: LocalAuthenticator
     :members:
 
+:class:`PAMAuthenticator`
+-------------------------
+
 .. autoconfigurable:: PAMAuthenticator
 

docs/source/api/index.rst

@@ -1,8 +1,8 @@
 .. _api-index:
 
-####################
- The JupyterHub API
-####################
+##################
+The JupyterHub API
+##################
 
 :Release: |release|
 :Date: |today|
@@ -31,6 +31,7 @@ JupyterHub API Reference:
     spawner
     proxy
     user
+    service
     services.auth
 
 

docs/source/api/proxy.rst

@@ -9,11 +9,15 @@ Module: :mod:`jupyterhub.proxy`
 
 .. currentmodule:: jupyterhub.proxy
 
-
+:class:`Proxy`
+--------------
 
 .. autoconfigurable:: Proxy
     :members:
 
+:class:`ConfigurableHTTPProxy`
+------------------------------
+
 .. autoconfigurable:: ConfigurableHTTPProxy
     :members: debug, auth_token, check_running_interval, api_url, command
 

docs/source/api/service.rst

@@ -0,0 +1,17 @@
+========
+Services
+========
+
+Module: :mod:`jupyterhub.services.service`
+==========================================
+
+.. automodule:: jupyterhub.services.service
+
+.. currentmodule:: jupyterhub.services.service
+
+:class:`Service`
+----------------
+
+.. autoconfigurable:: Service
+    :members: name, admin, url, api_token, managed, kind, command, cwd, environment, user, oauth_client_id, server, prefix, proxy_spec
+

docs/source/api/services.auth.rst

@@ -1,5 +1,5 @@
 =======================
-Authenticating Services
+Services Authentication
 =======================
 
 Module: :mod:`jupyterhub.services.auth`
@@ -10,9 +10,16 @@ Module: :mod:`jupyterhub.services.auth`
 .. currentmodule:: jupyterhub.services.auth
 
 
+:class:`HubAuth`
+----------------
+
 .. autoconfigurable:: HubAuth
     :members:
 
+
+:class:`HubAuthenticated`
+-------------------------
+
 .. autoclass:: HubAuthenticated
     :members:
 

docs/source/api/spawner.rst

@@ -1,6 +1,6 @@
-==============
-   Spawners
-==============
+========
+Spawners
+========
 
 Module: :mod:`jupyterhub.spawner`
 =================================
@@ -15,4 +15,8 @@ Module: :mod:`jupyterhub.spawner`
 .. autoconfigurable:: Spawner
     :members: options_from_form, poll, start, stop, get_args, get_env, get_state, template_namespace, format_string
 
+:class:`LocalProcessSpawner`
+----------------------------
+
 .. autoconfigurable:: LocalProcessSpawner
+

docs/source/api/user.rst

@@ -1,6 +1,6 @@
-=============
-   Users
-=============
+=====
+Users
+=====
 
 Module: :mod:`jupyterhub.user`
 ==============================
@@ -9,11 +9,16 @@ Module: :mod:`jupyterhub.user`
 
 .. currentmodule:: jupyterhub.user
 
+:class:`UserDict`
+-----------------
+
+.. autoclass:: UserDict
+    :members:
+
+
 :class:`User`
 -------------
 
-.. class:: Server
-
 .. autoclass:: User
     :members: escaped_name
     
@@ -29,3 +34,4 @@ Module: :mod:`jupyterhub.user`
     .. attribute:: spawner
     
         The user's :class:`~.Spawner` instance.
+

jupyterhub/services/auth.py

@@ -1,12 +1,14 @@
-"""Authenticating services with JupyterHub
+"""Authenticating services with JupyterHub.
 
-Cookies are sent to the Hub for verification, replying with a JSON model describing the authenticated user.
+Cookies are sent to the Hub for verification. The Hub replies with a JSON
+model describing the authenticated user.
 
-HubAuth can be used in any application, even outside tornado.
+``HubAuth`` can be used in any application, even outside tornado.
+
+``HubAuthenticated`` is a mixin class for tornado handlers that should
+authenticate with the Hub.
 
-HubAuthenticated is a mixin class for tornado handlers that should authenticate with the Hub.
 """
-
 import os
 import re
 import socket

jupyterhub/services/service.py

@@ -1,16 +1,15 @@
-"""A service is a process that talks to JupyterHub
+"""A service is a process that talks to JupyterHub.
 
-Cases:
-
-Managed:
+Types of services:
+    Managed:
       - managed by JupyterHub (always subprocess, no custom Spawners)
       - always a long-running process
       - managed services are restarted automatically if they exit unexpectedly
-Unmanaged:
+
+    Unmanaged:
       - managed by external service (docker, systemd, etc.)
       - do not need to be long-running processes, or processes at all
 
-
 URL: needs a route added to the proxy.
   - Public route will always be /services/service-name
   - url specified in config
@@ -30,13 +29,14 @@ An externally managed service running on a URL::
         'api_token': 'super-secret',
     }
 
-A hub-managed service with no URL:
+A hub-managed service with no URL::
 
     {
         'name': 'cull-idle',
         'command': ['python', '/path/to/cull-idle']
         'admin': True,
     }
+
 """
 
 import pipes