Add sphinx extension for documenting traits

Author: vidartf

docs/source/conf.py

@@ -13,14 +13,6 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-#
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
-
 
 # -- General configuration ------------------------------------------------
 
@@ -37,8 +29,17 @@
     'sphinx.ext.intersphinx',
     'sphinx.ext.napoleon',
     'sphinx.ext.todo',
+    'autodoc_traits',
 ]
 
+# Ensure our extension is available:
+import sys
+from os.path import dirname, join as pjoin
+docs = dirname(dirname(__file__))
+root = dirname(docs)
+sys.path.insert(0, pjoin(root, '..'))
+sys.path.insert(0, pjoin(docs, 'sphinxext'))
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 

docs/sphinxext/autodoc_traits.py

@@ -0,0 +1,91 @@
+"""autodoc extension for traits"""
+
+from collections import OrderedDict
+
+from traitlets import TraitType, Undefined, Container, Dict, Any
+from sphinx.ext.autodoc import ClassDocumenter, AttributeDocumenter
+
+
+def dict_info(trait):
+    trait_base = trait._trait
+    traits = trait._traits
+
+    if traits is None and (trait_base is None or isinstance(trait_base, Any)):
+        value_string = 'elements of any type'
+    else:
+        parts = []
+        if traits:
+            parts.append('the following types: %r' % {k: v.info() for k,v in traits})
+        if trait_base:
+            parts.append('values that are: %s' % trait_base.info())
+        value_string = 'elements with ' + ', and '.join(parts)
+
+    return '{} with {}'.format(trait.info(), value_string)
+
+
+def extended_trait_info(trait):
+    if isinstance(trait, Dict):
+        return dict_info(trait)
+    elif isinstance(trait, Container):
+        if trait._trait is None:
+            return '{} of any type'.format(trait.info())
+        return '{} with values that are: {}'.format(trait.info(), trait._trait.info())
+    return trait.info()
+
+
+class HasTraitsDocumenter(ClassDocumenter):
+    """Specialized Documenter subclass for traits"""
+    objtype = 'hastraits'
+    directivetype = 'class'
+
+    def get_object_members(self, want_all):
+        """Add traits 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
+        members_new = OrderedDict()
+        for m in members:
+            members_new[m[0]] = m[1]
+        traits = tuple(get_traits().items())
+        for name, trait in traits:
+            if name not in members_new:
+                # Don't add a member that would normally be filtered
+                continue
+                # pass # FIXME: Debugging
+
+            # put help in __doc__ where autodoc will look for it
+            trait.__doc__ = trait.help or extended_trait_info(getattr(self.object, name))
+            members_new[name] = trait
+
+        return check, [kv for kv in members_new.items()]
+
+
+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 self.objpath[-1]
+
+    def add_directive_header(self, sig):
+        default = self.object.get_default_value()
+        if default is Undefined:
+            default_s = ''
+        else:
+            default_s = repr(default)
+        sig = ' = {}({})'.format(
+            self.object.__class__.__name__,
+            default_s,
+        )
+        return super().add_directive_header(sig)
+
+
+def setup(app):
+    app.add_autodocumenter(HasTraitsDocumenter)
+    app.add_autodocumenter(TraitDocumenter)

js/scripts/templates/autodoc.mustache

@@ -4,7 +4,12 @@
 {{ className }}
 ====================================================
 
-.. py:class:: {{ className }}({{#unless constructor.hasParameters}}{{#each constructor.args as |arg|}}{{{ arg.name }}}{{#if arg.prop.defaultJson}}={{{ arg.prop.defaultJson }}}{{/if}}, {{/each}}{{/unless}})
+.. Use autoclass to fill any memebers not manually specified.
+   This ensures it picks up any members in overridden classes.
+
+.. autohastraits:: {{ className }}({{#unless constructor.hasParameters}}{{#each constructor.args as |arg|}}{{{ arg.name }}}{{#if arg.prop.defaultJson}}={{{ arg.prop.defaultJson }}}{{/if}}, {{/each}}{{/unless}})
+    :members:
+    :undoc-members:
 
     {{#if hasOverride}}
     This widget has some manual overrides on the Python side.
@@ -16,11 +21,6 @@
 
     Three.js docs: {{ threejs_docs_url }}
 
-    .. py:attribute:: _model_name
-
-        .. sourcecode:: python
-
-            Unicode('{{ modelName }}').tag(sync=True)
 
     {{#each properties as |prop propName|}}
     .. py:attribute:: {{ propName }}

js/scripts/templates/autodoc_index.mustache

@@ -5,7 +5,9 @@
 API Reference
 =============
 
-.. py:module:: pythreejs
+.. automodule:: pythreejs
+    :members:
+    :undoc-members:
 
 {{else}}
 
@@ -18,6 +20,6 @@ API Reference
 .. toctree::
     :maxdepth: 10
 
-{{#each submodules as |module|}}
+    {{#each submodules as |module|}}
     {{ module }}
-{{/each}}
+    {{/each}}