Merge pull request #2723 from willingc/use-autodoc

Use autodoc-traits sphinx extension

docs/environment.yml

@@ -24,3 +24,4 @@ dependencies:
   - attrs>=17.4.0
   - sphinx-copybutton
   - alabaster_jupyterhub
+  - autodoc-traits

docs/requirements.txt

@@ -2,6 +2,7 @@
 # if you change this file
 -r ../requirements.txt
 alabaster_jupyterhub
+autodoc-traits
 recommonmark==0.5.0
 sphinx-copybutton
 sphinx>=1.7

docs/source/conf.py

@@ -37,7 +37,6 @@ 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
 

docs/sphinxext/autodoc_traits.py

@@ -1,57 +0,0 @@
-"""autodoc extension for configurable traits"""
-from sphinx.domains.python import PyClassmember
-from sphinx.ext.autodoc import AttributeDocumenter
-from sphinx.ext.autodoc import ClassDocumenter
-from traitlets import TraitType
-from traitlets import Undefined
-
-
-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 add_directive_header(self, sig):
-        default = self.object.get_default_value()
-        if default is Undefined:
-            default_s = ''
-        else:
-            default_s = repr(default)
-        self.options.annotation = 'c.{name} = {trait}({default})'.format(
-            name=self.format_name(),
-            trait=self.object.__class__.__name__,
-            default=default_s,
-        )
-        super().add_directive_header(sig)
-
-
-def setup(app):
-    app.add_autodocumenter(ConfigurableDocumenter)
-    app.add_autodocumenter(TraitDocumenter)