matthew/enhanced-discord.py
1
0
Fork 0
Code Issues 4 Pull Requests 21 Projects Releases Wiki Activity

Add attributetable and add some class-level sections.

Browse Source 
The extensions have yet to receive this treatment and CSS needs work,
but for now this is fine.
This commit is contained in:
Rapptz
2020-05-25 11:48:16 -04:00
parent 1ee1b7feea
commit 771c1c85d8
5 changed files with 435 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
docs/_static/custom.js vendored
View File

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

25
docs/_static/style.css vendored
View File

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

204
docs/api.rst
View File

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

3
docs/conf.py
View File

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

199
docs/extensions/attributetable.py Normal file
View File

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