add configurable traits to api docs

docs/source/api/auth.rst

@@ -11,11 +11,11 @@ Module: :mod:`jupyterhub.auth`
 
 
 
-.. autoclass:: Authenticator
+.. autoconfigurable:: Authenticator
     :members:
 
-.. autoclass:: LocalAuthenticator
+.. autoconfigurable:: LocalAuthenticator
     :members:
 
-.. autoclass:: PAMAuthenticator
+.. autoconfigurable:: PAMAuthenticator
 

docs/source/api/index.rst

@@ -24,6 +24,7 @@ JupyterHub API Reference:
 
 .. toctree::
 
+    app
     auth
     spawner
     user

docs/source/api/services.auth.rst

@@ -10,7 +10,7 @@ Module: :mod:`jupyterhub.services.auth`
 .. currentmodule:: jupyterhub.services.auth
 
 
-.. autoclass:: HubAuth
+.. autoconfigurable:: HubAuth
     :members:
 
 .. autoclass:: HubAuthenticated

docs/source/api/spawner.rst

@@ -12,7 +12,7 @@ Module: :mod:`jupyterhub.spawner`
 :class:`Spawner`
 ----------------
 
-.. autoclass:: Spawner
+.. autoconfigurable:: Spawner
     :members: options_from_form, poll, start, stop, get_args, get_env, get_state, template_namespace, format_string
 
-.. autoclass:: LocalProcessSpawner
+.. autoconfigurable:: LocalProcessSpawner

docs/source/conf.py

@@ -20,6 +20,7 @@ extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.intersphinx',
     'sphinx.ext.napoleon',
+    'autodoc_traits',
 ]
 
 templates_path = ['_templates']
@@ -37,6 +38,7 @@ from os.path import dirname
 docs = dirname(dirname(__file__))
 root = dirname(docs)
 sys.path.insert(0, root)
+sys.path.insert(0, os.path.join(docs, 'sphinxext'))
 
 import jupyterhub
 # The short X.Y version.
@@ -49,6 +51,9 @@ exclude_patterns = []
 pygments_style = 'sphinx'
 todo_include_todos = False
 
+# Set the default role so we can use `foo` instead of ``foo``
+default_role = 'literal'
+
 # -- Source -------------------------------------------------------------
 
 source_parsers = {

docs/sphinxext/autodoc_traits.py

@@ -0,0 +1,49 @@
+"""autodoc extension for configurable traits"""
+
+from traitlets import TraitType
+from sphinx.domains.python import PyClassmember
+from sphinx.ext.autodoc import ClassDocumenter, AttributeDocumenter
+
+
+class ConfigurableDocumenter(ClassDocumenter):
+    """Specialized Documenter subclass for traits with config=True"""
+    objtype = 'configurable'
+    directivetype = 'class'
+
+    def get_object_members(self, want_all):
+        """Add traits with .tag(config=True) to members list"""
+        check, members = super().get_object_members(want_all)
+        get_traits = self.object.class_own_traits if self.options.inherited_members \
+                     else self.object.class_traits
+        trait_members = []
+        for name, trait in sorted(get_traits(config=True).items()):
+            # put help in __doc__ where autodoc will look for it
+            trait.__doc__ = trait.help
+            trait_members.append((name, trait))
+        return check, trait_members + members
+
+
+class TraitDocumenter(AttributeDocumenter):
+    objtype = 'trait'
+    directivetype = 'attribute'
+    member_order = 1
+    priority = 100
+
+    @classmethod
+    def can_document_member(cls, member, membername, isattr, parent):
+        return isinstance(member, TraitType)
+
+    def format_name(self):
+        return 'config c.' + super().format_name()
+
+    def add_directive_header(self, sig):
+        sig = ' = {}(default={!r})'.format(
+            self.object.__class__.__name__,
+            self.object.default(),
+        )
+        return super().add_directive_header(sig)
+
+
+def setup(app):
+    app.add_autodocumenter(ConfigurableDocumenter)
+    app.add_autodocumenter(TraitDocumenter)

jupyterhub/spawner.py

@@ -125,6 +125,8 @@ class Spawner(LoggingConfigurable):
         The surrounding `<form>` element and the submit button are already provided.
 
         For example:
+        
+        .. code:: html
 
             Set your key:
             <input name="key" val="default_key"></input>
@@ -250,6 +252,7 @@ class Spawner(LoggingConfigurable):
         `{username}` will be expanded to the user's username
 
         Example uses:
+
         - You can set `notebook_dir` to `/` and `default_url` to `/home/{username}` to allow people to
           navigate the whole filesystem from their notebook, but still start in their home directory.
         - You can set this to `/lab` to have JupyterLab start by default, rather than Jupyter Notebook.