diff --git a/docs/environment.yml b/docs/environment.yml index 2dbfd535..faa2f1ca 100644 --- a/docs/environment.yml +++ b/docs/environment.yml @@ -24,3 +24,4 @@ dependencies: - attrs>=17.4.0 - sphinx-copybutton - alabaster_jupyterhub + - autodoc-traits diff --git a/docs/requirements.txt b/docs/requirements.txt index 5f8b447a..44c782f0 100644 --- a/docs/requirements.txt +++ b/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 diff --git a/docs/source/conf.py b/docs/source/conf.py index 6e83f379..5f8d3632 100644 --- a/docs/source/conf.py +++ b/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 diff --git a/docs/sphinxext/autodoc_traits.py b/docs/sphinxext/autodoc_traits.py deleted file mode 100644 index 3d54f8bb..00000000 --- a/docs/sphinxext/autodoc_traits.py +++ /dev/null @@ -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)