From 875a701edb05eae9045de5b2d5111048c66db992 Mon Sep 17 00:00:00 2001 From: Rapptz Date: Sun, 28 Jun 2020 07:34:04 -0400 Subject: Rework attributetable to look prettier --- docs/extensions/attributetable.py | 88 +++++++++++++++++++++++++++------------ 1 file changed, 61 insertions(+), 27 deletions(-) (limited to 'docs/extensions') diff --git a/docs/extensions/attributetable.py b/docs/extensions/attributetable.py index aa34ec95..b173edab 100644 --- a/docs/extensions/attributetable.py +++ b/docs/extensions/attributetable.py @@ -3,7 +3,7 @@ from sphinx.locale import _ from docutils import nodes from sphinx import addnodes -from collections import OrderedDict +from collections import OrderedDict, namedtuple import importlib import inspect import os @@ -21,6 +21,12 @@ class attributetabletitle(nodes.TextElement): class attributetableplaceholder(nodes.General, nodes.Element): pass +class attributetablebadge(nodes.TextElement): + pass + +class attributetable_item(nodes.Part, nodes.Element): + pass + def visit_attributetable_node(self, node): self.body.append('
' % node['python-class']) @@ -30,6 +36,16 @@ def visit_attributetablecolumn_node(self, node): def visit_attributetabletitle_node(self, node): self.body.append(self.starttag(node, 'span')) +def visit_attributetablebadge_node(self, node): + attributes = { + 'class': 'py-attribute-table-badge', + 'title': node['badge-type'], + } + self.body.append(self.starttag(node, 'span', **attributes)) + +def visit_attributetable_item_node(self, node): + self.body.append(self.starttag(node, 'li', CLASS='py-attribute-table-entry')) + def depart_attributetable_node(self, node): self.body.append('
') @@ -39,6 +55,12 @@ def depart_attributetablecolumn_node(self, node): def depart_attributetabletitle_node(self, node): self.body.append('') +def depart_attributetablebadge_node(self, node): + self.body.append('') + +def depart_attributetable_item_node(self, node): + self.body.append('') + _name_parser_regex = re.compile(r'(?P[\w.]+\.)?(?P\w+)') class PyAttributeTable(SphinxDirective): @@ -68,22 +90,20 @@ class PyAttributeTable(SphinxDirective):
_('Attributes') -
-
- _('Coroutines') -
_('Methods')
- ... However, since this requires the tree to be complete @@ -120,6 +140,9 @@ def build_lookup_table(env): return result + +TableElement = namedtuple('TableElement', 'fullname label badge') + def process_attributetable(app, doctree, fromdocname): env = app.builder.env @@ -131,7 +154,7 @@ def process_attributetable(app, doctree, fromdocname): for label, subitems in groups.items(): if not subitems: continue - table.append(class_results_to_node(label, sorted(subitems))) + table.append(class_results_to_node(label, sorted(subitems, key=lambda c: c.label))) table['python-class'] = fullname @@ -145,11 +168,8 @@ def get_class_results(lookup, modulename, name, fullname): cls_dict = getattr(module, name).__dict__ groups = OrderedDict([ - ('Attributes', []), - ('Coroutines', []), - ('Classmethods', []), - ('Methods', []), - ('Decorators', []), + (_('Attributes'), []), + (_('Methods'), []), ]) try: @@ -159,38 +179,50 @@ def get_class_results(lookup, modulename, name, fullname): for attr in members: attrlookup = '%s.%s' % (fullname, attr) - key = 'Attributes' + key = _('Attributes') + badge = None label = attr value = cls_dict.get(attr) if value is not None: doc = value.__doc__ or '' if inspect.iscoroutinefunction(value) or doc.startswith('|coro|'): - key = 'Coroutines' + key = _('Methods') + badge = attributetablebadge('async', 'async') + badge['badge-type'] = _('coroutine') elif isinstance(value, classmethod): - key = 'Classmethods' + key = _('Methods') + label = '%s.%s' % (name, attr) + badge = attributetablebadge('cls', 'cls') + badge['badge-type'] = _('classmethod') elif inspect.isfunction(value): if doc.startswith(('A decorator', 'A shortcut decorator')): # finicky but surprisingly consistent - key = 'Decorators' + badge = attributetablebadge('@', '@') + badge['badge-type'] = _('decorator') + key = _('Methods') else: - key = 'Methods' + key = _('Methods') + badge = attributetablebadge('def', 'def') + badge['badge-type'] = _('method') - groups[key].append((attrlookup, label)) + groups[key].append(TableElement(fullname=attrlookup, label=label, badge=badge)) return groups def class_results_to_node(key, elements): title = attributetabletitle(key, key) ul = nodes.bullet_list('') - for fullname, label in elements: + for element in elements: ref = nodes.reference('', '', internal=True, - refuri='#' + fullname, + refuri='#' + element.fullname, anchorname='', - *[nodes.Text(label)]) + *[nodes.Text(element.label)]) para = addnodes.compact_paragraph('', '', ref) - item = nodes.list_item('', para) - ul.append(item) + if element.badge is not None: + ul.append(attributetable_item('', element.badge, para)) + else: + ul.append(attributetable_item('', para)) return attributetablecolumn('', title, ul) @@ -199,5 +231,7 @@ def setup(app): app.add_node(attributetable, html=(visit_attributetable_node, depart_attributetable_node)) app.add_node(attributetablecolumn, html=(visit_attributetablecolumn_node, depart_attributetablecolumn_node)) app.add_node(attributetabletitle, html=(visit_attributetabletitle_node, depart_attributetabletitle_node)) + app.add_node(attributetablebadge, html=(visit_attributetablebadge_node, depart_attributetablebadge_node)) + app.add_node(attributetable_item, html=(visit_attributetable_item_node, depart_attributetable_item_node)) app.add_node(attributetableplaceholder) app.connect('doctree-resolved', process_attributetable) -- cgit v1.2.3