Browse Source
The extensions have yet to receive this treatment and CSS needs work, but for now this is fine.pull/6176/head
Rapptz
5 years ago
5 changed files with 440 additions and 4 deletions
@ -0,0 +1,199 @@ |
|||||
|
from sphinx.util.docutils import SphinxDirective |
||||
|
from sphinx.locale import _ |
||||
|
from docutils import nodes |
||||
|
from sphinx import addnodes |
||||
|
|
||||
|
from collections import OrderedDict |
||||
|
import importlib |
||||
|
import inspect |
||||
|
import os |
||||
|
import re |
||||
|
|
||||
|
class attributetable(nodes.General, nodes.Element): |
||||
|
pass |
||||
|
|
||||
|
class attributetablecolumn(nodes.General, nodes.Element): |
||||
|
pass |
||||
|
|
||||
|
class attributetabletitle(nodes.TextElement): |
||||
|
pass |
||||
|
|
||||
|
class attributetableplaceholder(nodes.General, nodes.Element): |
||||
|
pass |
||||
|
|
||||
|
def visit_attributetable_node(self, node): |
||||
|
self.body.append('<div class="py-attribute-table" data-move-to-id="%s">' % node['python-class']) |
||||
|
|
||||
|
def visit_attributetablecolumn_node(self, node): |
||||
|
self.body.append(self.starttag(node, 'div', CLASS='py-attribute-table-column')) |
||||
|
|
||||
|
def visit_attributetabletitle_node(self, node): |
||||
|
self.body.append(self.starttag(node, 'span')) |
||||
|
|
||||
|
def depart_attributetable_node(self, node): |
||||
|
self.body.append('</div>') |
||||
|
|
||||
|
def depart_attributetablecolumn_node(self, node): |
||||
|
self.body.append('</div>') |
||||
|
|
||||
|
def depart_attributetabletitle_node(self, node): |
||||
|
self.body.append('</span>') |
||||
|
|
||||
|
_name_parser_regex = re.compile(r'(?P<module>[\w.]+\.)?(?P<name>\w+)') |
||||
|
|
||||
|
class PyAttributeTable(SphinxDirective): |
||||
|
has_content = False |
||||
|
required_arguments = 1 |
||||
|
optional_arguments = 0 |
||||
|
final_argument_whitespace = False |
||||
|
option_spec = {} |
||||
|
|
||||
|
def parse_name(self, content): |
||||
|
path, name = _name_parser_regex.match(content).groups() |
||||
|
if path: |
||||
|
modulename = path.rstrip('.') |
||||
|
else: |
||||
|
modulename = self.env.temp_data.get('autodoc:module') |
||||
|
if not modulename: |
||||
|
modulename = self.env.ref_context.get('py:module') |
||||
|
if modulename is None: |
||||
|
raise RuntimeError('modulename somehow None for %s in %s.' % (content, self.env.docname)) |
||||
|
|
||||
|
return modulename, name |
||||
|
|
||||
|
def run(self): |
||||
|
"""If you're curious on the HTML this is meant to generate: |
||||
|
|
||||
|
<div class="py-attribute-table"> |
||||
|
<div class="py-attribute-table-column"> |
||||
|
<span>_('Attributes')</span> |
||||
|
<ul> |
||||
|
<li><a href="..."></li> |
||||
|
</ul> |
||||
|
</div> |
||||
|
<div class="py-attribute-table-column"> |
||||
|
<span>_('Coroutines')</span> |
||||
|
<ul> |
||||
|
<li><a href="..."></li> |
||||
|
</ul> |
||||
|
</div> |
||||
|
<div class="py-attribute-table-column"> |
||||
|
<span>_('Methods')</span> |
||||
|
<ul> |
||||
|
<li><a href="..."></li> |
||||
|
</ul> |
||||
|
</div> |
||||
|
... |
||||
|
</div> |
||||
|
|
||||
|
However, since this requires the tree to be complete |
||||
|
and parsed, it'll need to be done at a different stage and then |
||||
|
replaced. |
||||
|
""" |
||||
|
content = self.arguments[0].strip() |
||||
|
node = attributetableplaceholder('') |
||||
|
modulename, name = self.parse_name(content) |
||||
|
node['python-module'] = modulename |
||||
|
node['python-class'] = name |
||||
|
node['python-full-name'] = '%s.%s' % (modulename, name) |
||||
|
return [node] |
||||
|
|
||||
|
def build_lookup_table(env): |
||||
|
# Given an environment, load up a lookup table of |
||||
|
# full-class-name: objects |
||||
|
result = {} |
||||
|
domain = env.domains['py'] |
||||
|
|
||||
|
ignored = { |
||||
|
'data', 'exception', 'module', 'class', |
||||
|
} |
||||
|
for (fullname, (docname, objtype)) in domain.objects.items(): |
||||
|
if objtype in ignored: |
||||
|
continue |
||||
|
|
||||
|
classname, _, child = fullname.rpartition('.') |
||||
|
try: |
||||
|
result[classname].append(child) |
||||
|
except KeyError: |
||||
|
result[classname] = [child] |
||||
|
|
||||
|
return result |
||||
|
|
||||
|
def process_attributetable(app, doctree, fromdocname): |
||||
|
env = app.builder.env |
||||
|
|
||||
|
lookup = build_lookup_table(env) |
||||
|
for node in doctree.traverse(attributetableplaceholder): |
||||
|
modulename, classname, fullname = node['python-module'], node['python-class'], node['python-full-name'] |
||||
|
groups = get_class_results(lookup, modulename, classname, fullname) |
||||
|
table = attributetable('') |
||||
|
for label, subitems in groups.items(): |
||||
|
if not subitems: |
||||
|
continue |
||||
|
table.append(class_results_to_node(label, subitems)) |
||||
|
|
||||
|
table['python-class'] = fullname |
||||
|
|
||||
|
if not table: |
||||
|
node.replace_self([]) |
||||
|
else: |
||||
|
node.replace_self([table]) |
||||
|
|
||||
|
def get_class_results(lookup, modulename, name, fullname): |
||||
|
module = importlib.import_module(modulename) |
||||
|
cls_dict = getattr(module, name).__dict__ |
||||
|
|
||||
|
groups = OrderedDict([ |
||||
|
('Attributes', []), |
||||
|
('Coroutines', []), |
||||
|
('Methods', []), |
||||
|
('Decorators', []), |
||||
|
]) |
||||
|
|
||||
|
try: |
||||
|
members = lookup[fullname] |
||||
|
except KeyError: |
||||
|
return groups |
||||
|
|
||||
|
for attr in members: |
||||
|
attrlookup = '%s.%s' % (fullname, attr) |
||||
|
key = 'Attributes' |
||||
|
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' |
||||
|
elif inspect.isfunction(value): |
||||
|
if doc.startswith(('A decorator', 'A shortcut decorator')): |
||||
|
# finicky but surprisingly consistent |
||||
|
key = 'Decorators' |
||||
|
else: |
||||
|
key = 'Methods' |
||||
|
|
||||
|
groups[key].append((attrlookup, label)) |
||||
|
|
||||
|
return groups |
||||
|
|
||||
|
def class_results_to_node(key, elements): |
||||
|
title = attributetabletitle(key, key) |
||||
|
ul = nodes.bullet_list('') |
||||
|
for fullname, label in elements: |
||||
|
ref = nodes.reference('', '', internal=True, |
||||
|
refuri='#' + fullname, |
||||
|
anchorname='', |
||||
|
*[nodes.Text(label)]) |
||||
|
para = addnodes.compact_paragraph('', '', ref) |
||||
|
item = nodes.list_item('', para) |
||||
|
ul.append(item) |
||||
|
|
||||
|
return attributetablecolumn('', title, ul) |
||||
|
|
||||
|
def setup(app): |
||||
|
app.add_directive('attributetable', PyAttributeTable) |
||||
|
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(attributetableplaceholder) |
||||
|
app.connect('doctree-resolved', process_attributetable) |
||||
Loading…
Reference in new issue