Add attributetable and add some class-level sections.

The extensions have yet to receive this treatment and CSS needs work,
but for now this is fine.

docs/_static/custom.js

@@ -27,5 +27,13 @@ $(document).ready(function () {
       activeLink = $('.sphinxsidebar a[href="#' + currentSection.attr('id') + '"]');
       activeLink.parent().addClass('active');
     }
+
+    const tables = document.querySelectorAll('.py-attribute-table[data-move-to-id]');
+    tables.forEach(table => {
+      let element = document.getElementById(table.getAttribute('data-move-to-id'));
+      let parent = element.parentNode;
+      // insert ourselves after the element
+      parent.insertBefore(table, element.nextSibling);
+    });
   });
 });

docs/_static/style.css

@@ -278,6 +278,12 @@ div.attention, div.warning, div.caution, div.seealso {
   border: 1px solid #fbe091;
 }
 
+dl.field-list > dd {
+  margin-top: 3px;
+  margin-bottom: 10px;
+  margin-left: 20px;
+}
+
 /* no disgusting background in the FAQ */
 div.topic {
   background-color: transparent;
@@ -352,6 +358,25 @@ div.helpful > p.admonition-title:after {
   list-style: '»' !important;
 }
 
+/* attribute tables */
+.py-attribute-table {
+  display: flex;
+  flex-direction: row;
+  justify-content: space-between;
+  margin: 0 2em;
+  padding-top: 16px;
+}
+
+.py-attribute-table-column > span {
+  font-weight: bold;
+}
+
+div.body .py-attribute-table-column > ul {
+  list-style: none;
+  margin: 4px 0px;
+  padding-left: 12px;
+}
+
 pre {
   background-color: #f5f5f5;
   border: 1px solid #C6C9CB;

docs/api.rst

@@ -30,45 +30,108 @@ There are two main ways to query version information about the library. For guar
     A string representation of the version. e.g. ``'1.0.0rc1'``. This is based
     off of :pep:`440`.
 
+Clients
+--------
+
 Client
--------
+~~~~~~~
+
+.. attributetable:: Client
 
 .. autoclass:: Client
     :members:
 
+AutoShardedClient
+~~~~~~~~~~~~~~~~~~
+
+.. attributetable:: AutoShardedClient
+
 .. autoclass:: AutoShardedClient
     :members:
 
+Application Info
+------------------
+
+AppInfo
+~~~~~~~~
+
+.. attributetable:: AppInfo
+
 .. autoclass:: AppInfo()
     :members:
 
+Team
+~~~~~
+
+.. attributetable:: Team
+
 .. autoclass:: Team()
     :members:
 
+TeamMember
+~~~~~~~~~~~
+
+.. attributetable:: TeamMember
+
 .. autoclass:: TeamMember()
     :members:
 
-Voice
+Voice Related
-------
+---------------
+
+VoiceClient
+~~~~~~~~~~~~
+
+.. attributetable:: VoiceClient
 
 .. autoclass:: VoiceClient()
     :members:
 
+AudioSource
+~~~~~~~~~~~~
+
+.. attributetable:: AudioSource
+
 .. autoclass:: AudioSource
     :members:
 
+PCMAudio
+~~~~~~~~~
+
+.. attributetable:: PCMAudio
+
 .. autoclass:: PCMAudio
     :members:
 
+FFmpegAudio
+~~~~~~~~~~~~
+
+.. attributetable:: FFmpegAudio
+
 .. autoclass:: FFmpegAudio
     :members:
 
+FFmpegPCMAudio
+~~~~~~~~~~~~~~~
+
+.. attributetable:: FFmpegPCMAudio
+
 .. autoclass:: FFmpegPCMAudio
     :members:
 
+FFmpegOpusAudio
+~~~~~~~~~~~~~~~~
+
+.. attributetable:: FFmpegOpusAudio
+
 .. autoclass:: FFmpegOpusAudio
     :members:
 
+PCMVolumeTransformer
+~~~~~~~~~~~~~~~~~~~~~
+
+.. attributetable:: PCMVolumeTransformer
+
 .. autoclass:: PCMVolumeTransformer
     :members:
 
@@ -1901,9 +1964,19 @@ Working with :meth:`Guild.audit_logs` is a complicated process with a lot of mac
 involved. The library attempts to make it easy to use and friendly. In order to accomplish
 this goal, it must make use of a couple of data classes that aid in this goal.
 
+AuditLogEntry
+~~~~~~~~~~~~~~~
+
+.. attributetable:: AuditLogEntry
+
 .. autoclass:: AuditLogEntry
     :members:
 
+AuditLogChanges
+~~~~~~~~~~~~~~~~~
+
+.. attributetable:: AuditLogChanges
+
 .. class:: AuditLogChanges
 
     An audit log change set.
@@ -1948,6 +2021,11 @@ this goal, it must make use of a couple of data classes that aid in this goal.
         | ``None``                               | No attributes are set.                           |
         +----------------------------------------+--------------------------------------------------+
 
+AuditLogDiff
+~~~~~~~~~~~~~
+
+.. attributetable:: AuditLogDiff
+
 .. class:: AuditLogDiff
 
     Represents an audit log "change" object. A change object has dynamic
@@ -2213,6 +2291,8 @@ Webhook Support
 
 discord.py offers support for creating, editing, and executing webhooks through the :class:`Webhook` class.
 
+.. attributetable:: Webhook
+
 .. autoclass:: Webhook
     :members:
 
@@ -2244,18 +2324,43 @@ They are mainly there for usage with :func:`py:isinstance` and :func:`py:issubcl
 This library has a module related to abstract base classes, some of which are actually from the :doc:`abc <py:library/abc>` standard
 module, others which are not.
 
+Snowflake
+~~~~~~~~~~
+
+.. attributetable:: discord.abc.Snowflake
+
 .. autoclass:: discord.abc.Snowflake
     :members:
 
+User
+~~~~~
+
+.. attributetable:: discord.abc.User
+
 .. autoclass:: discord.abc.User
     :members:
 
+PrivateChannel
+~~~~~~~~~~~~~~~
+
+.. attributetable:: discord.abc.PrivateChannel
+
 .. autoclass:: discord.abc.PrivateChannel
     :members:
 
+GuildChannel
+~~~~~~~~~~~~~
+
+.. attributetable:: discord.abc.GuildChannel
+
 .. autoclass:: discord.abc.GuildChannel
     :members:
 
+Messageable
+~~~~~~~~~~~~
+
+.. attributetable:: discord.abc.Messageable
+
 .. autoclass:: discord.abc.Messageable
     :members:
     :exclude-members: history, typing
@@ -2266,6 +2371,11 @@ module, others which are not.
     .. automethod:: discord.abc.Messageable.typing
         :async-with:
 
+Connectable
+~~~~~~~~~~~~
+
+.. attributetable:: discord.abc.Connectable
+
 .. autoclass:: discord.abc.Connectable
 
 .. _discord_api_models:
@@ -2298,6 +2408,8 @@ the user of the library.
 ClientUser
 ~~~~~~~~~~~~
 
+.. attributetable:: ClientUser
+
 .. autoclass:: ClientUser()
     :members:
     :inherited-members:
@@ -2305,12 +2417,16 @@ ClientUser
 Relationship
 ~~~~~~~~~~~~~~
 
+.. attributetable:: Relationship
+
 .. autoclass:: Relationship()
     :members:
 
 User
 ~~~~~
 
+.. attributetable:: User
+
 .. autoclass:: User()
     :members:
     :inherited-members:
@@ -2325,24 +2441,32 @@ User
 Attachment
 ~~~~~~~~~~~
 
+.. attributetable:: Attachment
+
 .. autoclass:: Attachment()
     :members:
 
 Asset
 ~~~~~
 
+.. attributetable:: Asset
+
 .. autoclass:: Asset()
     :members:
 
 Message
 ~~~~~~~
 
+.. attributetable:: Message
+
 .. autoclass:: Message()
     :members:
 
 Reaction
 ~~~~~~~~~
 
+.. attributetable:: Reaction
+
 .. autoclass:: Reaction()
     :members:
     :exclude-members: users
@@ -2353,18 +2477,24 @@ Reaction
 CallMessage
 ~~~~~~~~~~~~
 
+.. attributetable:: CallMessage
+
 .. autoclass:: CallMessage()
     :members:
 
 GroupCall
 ~~~~~~~~~~
 
+.. attributetable:: GroupCall
+
 .. autoclass:: GroupCall()
     :members:
 
 Guild
 ~~~~~~
 
+.. attributetable:: Guild
+
 .. autoclass:: Guild()
     :members:
     :exclude-members: audit_logs
@@ -2375,6 +2505,8 @@ Guild
 Member
 ~~~~~~
 
+.. attributetable:: Member
+
 .. autoclass:: Member()
     :members:
     :inherited-members:
@@ -2389,36 +2521,48 @@ Member
 Spotify
 ~~~~~~~~
 
+.. attributetable:: Spotify
+
 .. autoclass:: Spotify()
     :members:
 
 VoiceState
 ~~~~~~~~~~~
 
+.. attributetable:: VoiceState
+
 .. autoclass:: VoiceState()
     :members:
 
 Emoji
 ~~~~~
 
+.. attributetable:: Emoji
+
 .. autoclass:: Emoji()
     :members:
 
 PartialEmoji
 ~~~~~~~~~~~~~~~~~~~~~~
 
+.. attributetable:: PartialEmoji
+
 .. autoclass:: PartialEmoji()
     :members:
 
 Role
 ~~~~~
 
+.. attributetable:: Role
+
 .. autoclass:: Role()
     :members:
 
 TextChannel
 ~~~~~~~~~~~~
 
+.. attributetable:: TextChannel
+
 .. autoclass:: TextChannel()
     :members:
     :inherited-members:
@@ -2433,6 +2577,8 @@ TextChannel
 VoiceChannel
 ~~~~~~~~~~~~~
 
+.. attributetable:: VoiceChannel
+
 .. autoclass:: VoiceChannel()
     :members:
     :inherited-members:
@@ -2440,6 +2586,8 @@ VoiceChannel
 CategoryChannel
 ~~~~~~~~~~~~~~~~~
 
+.. attributetable:: CategoryChannel
+
 .. autoclass:: CategoryChannel()
     :members:
     :inherited-members:
@@ -2447,6 +2595,8 @@ CategoryChannel
 DMChannel
 ~~~~~~~~~
 
+.. attributetable:: DMChannel
+
 .. autoclass:: DMChannel()
     :members:
     :inherited-members:
@@ -2461,6 +2611,8 @@ DMChannel
 GroupChannel
 ~~~~~~~~~~~~
 
+.. attributetable:: GroupChannel
+
 .. autoclass:: GroupChannel()
     :members:
     :inherited-members:
@@ -2475,30 +2627,40 @@ GroupChannel
 PartialInviteGuild
 ~~~~~~~~~~~~~~~~~~~
 
+.. attributetable:: PartialInviteGuild
+
 .. autoclass:: PartialInviteGuild()
     :members:
 
 PartialInviteChannel
 ~~~~~~~~~~~~~~~~~~~~~
 
+.. attributetable:: PartialInviteChannel
+
 .. autoclass:: PartialInviteChannel()
     :members:
 
 Invite
 ~~~~~~~
 
+.. attributetable:: Invite
+
 .. autoclass:: Invite()
     :members:
 
 WidgetChannel
 ~~~~~~~~~~~~~~~
 
+.. attributetable:: WidgetChannel
+
 .. autoclass:: WidgetChannel()
     :members:
 
 WidgetMember
 ~~~~~~~~~~~~~
 
+.. attributetable:: WidgetMember
+
 .. autoclass:: WidgetMember()
     :members:
     :inherited-members:
@@ -2506,42 +2668,56 @@ WidgetMember
 Widget
 ~~~~~~~
 
+.. attributetable:: Widget
+
 .. autoclass:: Widget()
     :members:
 
 RawMessageDeleteEvent
 ~~~~~~~~~~~~~~~~~~~~~~~
 
+.. attributetable:: RawMessageDeleteEvent
+
 .. autoclass:: RawMessageDeleteEvent()
     :members:
 
 RawBulkMessageDeleteEvent
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+.. attributetable:: RawBulkMessageDeleteEvent
+
 .. autoclass:: RawBulkMessageDeleteEvent()
     :members:
 
 RawMessageUpdateEvent
 ~~~~~~~~~~~~~~~~~~~~~~
 
+.. attributetable:: RawMessageUpdateEvent
+
 .. autoclass:: RawMessageUpdateEvent()
     :members:
 
 RawReactionActionEvent
 ~~~~~~~~~~~~~~~~~~~~~~~
 
+.. attributetable:: RawReactionActionEvent
+
 .. autoclass:: RawReactionActionEvent()
     :members:
 
 RawReactionClearEvent
 ~~~~~~~~~~~~~~~~~~~~~~
 
+.. attributetable:: RawReactionClearEvent
+
 .. autoclass:: RawReactionClearEvent()
     :members:
 
 RawReactionClearEmojiEvent
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+.. attributetable:: RawReactionClearEmojiEvent
+
 .. autoclass:: RawReactionClearEmojiEvent()
     :members:
 
@@ -2572,66 +2748,88 @@ Object
 Embed
 ~~~~~~
 
+.. attributetable:: Embed
+
 .. autoclass:: Embed
     :members:
 
 AllowedMentions
 ~~~~~~~~~~~~~~~~~
 
+.. attributetable:: AllowedMentions
+
 .. autoclass:: AllowedMentions
     :members:
 
 File
 ~~~~~
 
+.. attributetable:: File
+
 .. autoclass:: File
     :members:
 
 Colour
 ~~~~~~
 
+.. attributetable:: Colour
+
 .. autoclass:: Colour
     :members:
 
 BaseActivity
 ~~~~~~~~~~~~~~
 
+.. attributetable:: BaseActivity
+
 .. autoclass:: BaseActivity
     :members:
 
 Activity
 ~~~~~~~~~
 
+.. attributetable:: Activity
+
 .. autoclass:: Activity
     :members:
 
 Game
 ~~~~~
 
+.. attributetable:: Game
+
 .. autoclass:: Game
     :members:
 
 Streaming
 ~~~~~~~~~~~
 
+.. attributetable:: Streaming
+
 .. autoclass:: Streaming
     :members:
 
 CustomActivity
 ~~~~~~~~~~~~~~~
 
+.. attributetable:: CustomActivity
+
 .. autoclass:: CustomActivity
     :members:
 
 Permissions
 ~~~~~~~~~~~~
 
+.. attributetable:: Permissions
+
 .. autoclass:: Permissions
     :members:
 
 PermissionOverwrite
 ~~~~~~~~~~~~~~~~~~~~
 
+.. attributetable:: PermissionOverwrite
+
 .. autoclass:: PermissionOverwrite
     :members:
 

docs/conf.py

@@ -38,7 +38,8 @@ extensions = [
     'sphinx.ext.napoleon',
     'sphinxcontrib_trio',
     'details',
-    'exception_hierarchy'
+    'exception_hierarchy',
+    'attributetable',
 ]
 
 autodoc_member_order = 'bysource'

docs/extensions/attributetable.py

@@ -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)