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

Fix various reference issues in documentation

Browse Source 
Co-Authored-By: Riley Shaw <30989490+ShineyDev@users.noreply.github.com>
This commit is contained in:
Josh 2021-05-06 21:51:07 +10:00 committed by GitHub
parent 1bf7aadf94
commit 3864fb37a0
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
24 changed files with 106 additions and 52 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
discord/abc.py
View File

@ -114,7 +114,7 @@ class User(Snowflake, Protocol):
The user's username.
discriminator: :class:`str`
The user's discriminator.
avatar: :class:`Asset`
avatar: :class:`~discord.Asset`
The avatar asset the user has.
bot: :class:`bool`
If the user is a bot account.
@ -634,7 +634,7 @@ class GuildChannel:
Deletes the channel.
You must have :attr:`~Permissions.manage_channels` permission to use this.
You must have :attr:`~discord.Permissions.manage_channels` permission to use this.
Parameters
-----------
@ -678,7 +678,7 @@ class GuildChannel:
If the ``overwrite`` parameter is ``None``, then the permission
overwrites are deleted.
You must have the :attr:`~Permissions.manage_roles` permission to use this.
You must have the :attr:`~discord.Permissions.manage_roles` permission to use this.
Examples
----------
@ -860,7 +860,7 @@ class GuildChannel:
A rich interface to help move a channel relative to other channels.
If exact position movement is required, :meth:`edit` should be used instead.
If exact position movement is required, ``edit`` should be used instead.
You must have the :attr:`~discord.Permissions.manage_channels` permission to
do this.
@ -990,7 +990,7 @@ class GuildChannel:
Creates an instant invite from a text or voice channel.
You must have the :attr:`~Permissions.create_instant_invite` permission to
You must have the :attr:`~discord.Permissions.create_instant_invite` permission to
do this.
Parameters
@ -1040,7 +1040,7 @@ class GuildChannel:
Returns a list of all active instant invites from this channel.
You must have :attr:`~Permissions.manage_channels` to get this information.
You must have :attr:`~discord.Permissions.manage_channels` to get this information.
Raises
-------
@ -1321,7 +1321,7 @@ class Messageable(Protocol):
def history(self, *, limit=100, before=None, after=None, around=None, oldest_first=None):
"""Returns an :class:`~discord.AsyncIterator` that enables receiving the destination's message history.
You must have :attr:`~Permissions.read_message_history` permissions to use this.
You must have :attr:`~discord.Permissions.read_message_history` permissions to use this.
Examples
---------

6
discord/client.py
View File

@ -287,13 +287,13 @@ class Client:
If this is not passed via ``__init__`` then this is retrieved
through the gateway when an event contains the data. Usually
after :func:`on_connect` is called.
after :func:`~discord.on_connect` is called.
"""
return self._connection.application_id
@property
def application_flags(self) -> ApplicationFlags:
""":class:`ApplicationFlags`: The client's application flags.
""":class:`~discord.ApplicationFlags`: The client's application flags.
.. versionadded: 2.0
"""
@ -1261,7 +1261,7 @@ class Client:
.. note::
This method is an API call. If you have :attr:`Intents.members` and member cache enabled, consider :meth:`get_user` instead.
This method is an API call. If you have :attr:`discord.Intents.members` and member cache enabled, consider :meth:`get_user` instead.
Parameters
-----------

4
discord/ext/commands/bot.py
View File

@ -220,7 +220,7 @@ class BotBase(GroupMixin):
The function that was used as a global check.
call_once: :class:`bool`
If the function should only be called once per
:meth:`.Command.invoke` call.
:meth:`.invoke` call.
"""
if call_once:
@ -253,7 +253,7 @@ class BotBase(GroupMixin):
r"""A decorator that adds a "call once" global check to the bot.
Unlike regular global checks, this one is called only once
per :meth:`.Command.invoke` call.
per :meth:`.invoke` call.
Regular global checks are called whenever a command is called
or :meth:`.Command.can_run` is called. This type of check

2
discord/ext/commands/cog.py
View File

@ -334,7 +334,7 @@ class Cog(metaclass=CogMeta):
@_cog_special_method
def cog_check(self, ctx):
"""A special method that registers as a :func:`commands.check`
"""A special method that registers as a :func:`~discord.ext.commands.check`
for every command and subcommand in this cog.
This function **can** be a coroutine and must take a sole parameter,

4
discord/ext/commands/context.py
View File

@ -47,12 +47,12 @@ class Context(discord.abc.Messageable):
The bot that contains the command being executed.
args: :class:`list`
The list of transformed arguments that were passed into the command.
If this is accessed during the :func:`on_command_error` event
If this is accessed during the :func:`.on_command_error` event
then this list could be incomplete.
kwargs: :class:`dict`
A dictionary of transformed arguments that were passed into the command.
Similar to :attr:`args`\, if this is accessed in the
:func:`on_command_error` event then this dict could be incomplete.
:func:`.on_command_error` event then this dict could be incomplete.
current_parameter: Optional[:class:`inspect.Parameter`]
The parameter that is currently being inspected and converted.
This is only of use for within converters.

2
discord/ext/commands/converter.py
View File

@ -516,7 +516,7 @@ class ColourConverter(Converter[discord.Colour]):
- ``#<hex>``
- ``0x#<hex>``
- ``rgb(<number>, <number>, <number>)``
- Any of the ``classmethod`` in :class:`Colour`
- Any of the ``classmethod`` in :class:`~discord.Colour`
- The ``_`` in the name can be optionally replaced with spaces.

6
discord/ext/commands/core.py
View File

@ -908,9 +908,9 @@ class Command(_BaseCommand):
def short_doc(self):
""":class:`str`: Gets the "short" documentation of a command.
By default, this is the :attr:`brief` attribute.
By default, this is the :attr:`.brief` attribute.
If that lookup leads to an empty string then the first line of the
:attr:`help` attribute is used instead.
:attr:`.help` attribute is used instead.
"""
if self.brief is not None:
return self.brief
@ -979,7 +979,7 @@ class Command(_BaseCommand):
"""|coro|
Checks if the command can be executed by checking all the predicates
inside the :attr:`checks` attribute. This also checks whether the
inside the :attr:`~Command.checks` attribute. This also checks whether the
command is disabled.
.. versionchanged:: 1.3

8
discord/ext/commands/errors.py
View File

@ -89,7 +89,7 @@ class CommandError(DiscordException):
This exception and exceptions inherited from it are handled
in a special way as they are caught and passed into a special event
from :class:`.Bot`\, :func:`on_command_error`.
from :class:`.Bot`\, :func:`.on_command_error`.
"""
def __init__(self, message=None, *args):
if message is not None:
@ -457,7 +457,7 @@ class CommandOnCooldown(CommandError):
Attributes
-----------
cooldown: Cooldown
cooldown: ``Cooldown``
A class with attributes ``rate``, ``per``, and ``type`` similar to
the :func:`.cooldown` decorator.
retry_after: :class:`float`
@ -654,7 +654,7 @@ class BadUnionArgument(UserInputError):
-----------
param: :class:`inspect.Parameter`
The parameter that failed being converted.
converters: Tuple[Type, ...]
converters: Tuple[Type, ``...``]
A tuple of converters attempted in conversion, in order of failure.
errors: List[:class:`CommandError`]
A list of errors that were caught from failing the conversion.
@ -692,7 +692,7 @@ class BadLiteralArgument(UserInputError):
-----------
param: :class:`inspect.Parameter`
The parameter that failed being converted.
literals: Tuple[Any, ...]
literals: Tuple[Any, ``...``]
A tuple of values compared against in conversion, in order of failure.
errors: List[:class:`CommandError`]
A list of errors that were caught from failing the conversion.

11
discord/ext/commands/help.py
View File

@ -277,9 +277,9 @@ class HelpCommand:
Defaults to ``False``.
verify_checks: Optional[:class:`bool`]
Specifies if commands should have their :attr:`.Command.checks` called
and verified. If ``True``, always calls :attr:`.Commands.checks`.
If ``None``, only calls :attr:`.Commands.checks` in a guild setting.
If ``False``, never calls :attr:`.Commands.checks`. Defaults to ``True``.
and verified. If ``True``, always calls :attr:`.Command.checks`.
If ``None``, only calls :attr:`.Command.checks` in a guild setting.
If ``False``, never calls :attr:`.Command.checks`. Defaults to ``True``.
.. versionchanged:: 1.7
command_attrs: :class:`dict`
@ -615,8 +615,7 @@ class HelpCommand:
"""|coro|
Handles the implementation when an error happens in the help command.
For example, the result of :meth:`command_not_found` or
:meth:`command_has_no_subcommand_found` will be passed here.
For example, the result of :meth:`command_not_found` will be passed here.
You can override this method to customise the behaviour.
@ -949,7 +948,7 @@ class DefaultHelpCommand(HelpCommand):
if the list of commands is greater than 0.
max_size: Optional[:class:`int`]
The max size to use for the gap between indents.
If unspecified, calls :meth:`get_max_size` on the
If unspecified, calls :meth:`~HelpCommand.get_max_size` on the
commands parameter.
"""

4
discord/guild.py
View File

@ -143,7 +143,7 @@ class Guild(Hashable):
- ``COMMERCE``: Guild can sell things using store channels.
- ``PUBLIC``: Guild is a public guild.
- ``NEWS``: Guild can create news channels.
- ``BANNER``: Guild can upload and use a banner (i.e. :meth:`banner_url`).
- ``BANNER``: Guild can upload and use a banner. (i.e. :attr:`.banner`)
- ``ANIMATED_ICON``: Guild can upload an animated icon.
- ``PUBLIC_DISABLED``: Guild cannot be public.
- ``WELCOME_SCREEN_ENABLED``: Guild has enabled the welcome screen
@ -1042,7 +1042,7 @@ class Guild(Hashable):
The new name of the guild.
description: Optional[:class:`str`]
The new description of the guild. Could be ``None`` for no description.
This is only available to guilds that contain ``PUBLIC`` in :attr:`Guild.features`.
This is only available to guilds that contain ``PUBLIC`` in :attr:`Guild.features`.
icon: :class:`bytes`
A :term:`py:bytes-like object` representing the icon. Only PNG/JPEG is supported.
GIF is only available to guilds that contain ``ANIMATED_ICON`` in :attr:`Guild.features`.

2
discord/invite.py
View File

@ -281,7 +281,7 @@ class Invite(Hashable):
The target of this invite in the case of stream invites.
.. versionadded:: 2.0
target_type: :class:`InviteType`
target_type: :class:`InviteTarget`
The invite's target type.
.. versionadded:: 2.0

2
discord/player.py
View File

@ -73,7 +73,7 @@ class AudioSource:
If the audio is complete, then returning an empty
:term:`py:bytes-like object` to signal this is the way to do so.
If :meth:`is_opus` method returns ``True``, then it must return
If :meth:`~AudioSource.is_opus` method returns ``True``, then it must return
20ms worth of Opus encoded audio. Otherwise, it must be 20ms
worth of 16-bit 48KHz stereo PCM, which is about 3,840 bytes
per frame (20ms worth of audio).

4
discord/utils.py
View File

@ -353,7 +353,7 @@ def find(predicate: Callable[[T], Any], seq: Iterable[T]) -> Optional[T]:
-----------
predicate
A function that returns a boolean-like result.
seq: iterable
seq: :class:`collections.abc.Iterable`
The iterable to search through.
"""
@ -530,7 +530,7 @@ async def sleep_until(when: datetime.datetime, result: Optional[T] = None) -> Op
def utcnow() -> datetime.datetime:
"""A helper function to return an aware UTC datetime representing the current time.
This should be preferred to :func:`datetime.datetime.utcnow` since it is an aware
This should be preferred to :meth:`datetime.datetime.utcnow` since it is an aware
datetime, compared to the naive datetime in the standard library.
.. versionadded:: 2.0

2
discord/voice_client.py
View File

@ -71,7 +71,7 @@ class VoiceProtocol:
This class allows you to implement a protocol to allow for an external
method of sending voice, such as Lavalink_ or a native library implementation.
These classes are passed to :meth:`abc.Connectable.connect`.
These classes are passed to :meth:`abc.Connectable.connect <VoiceChannel.connect>`.
.. _Lavalink: https://github.com/freyacodes/Lavalink

2
discord/webhook/async_.py
View File

@ -788,8 +788,6 @@ class Webhook(BaseWebhook):
received without authentication then this will be ``None``.
name: Optional[:class:`str`]
The default name of the webhook.
avatar: Optional[:class:`str`]
The default avatar of the webhook.
source_guild: Optional[:class:`PartialWebhookGuild`]
The guild of the channel that this webhook is following.
Only given if :attr:`type` is :attr:`WebhookType.channel_follower`.

2
discord/webhook/sync.py
View File

@ -478,8 +478,6 @@ class SyncWebhook(BaseWebhook):
received without authentication then this will be ``None``.
name: Optional[:class:`str`]
The default name of the webhook.
avatar: Optional[:class:`str`]
The default avatar of the webhook.
source_guild: Optional[:class:`PartialWebhookGuild`]
The guild of the channel that this webhook is following.
Only given if :attr:`type` is :attr:`WebhookType.channel_follower`.

63
docs/api.rst
View File

@ -367,7 +367,7 @@ to handle it, which defaults to print a traceback and ignoring the exception.
Messages might not be in cache if the message is too old
or the client is participating in high traffic guilds.
If this occurs increase the :attr:`Client.max_messages` attribute
If this occurs increase the :class:`max_messages <Client>` parameter
or use the :func:`on_raw_message_delete` event instead.
This requires :attr:`Intents.messages` to be enabled.
@ -384,7 +384,7 @@ to handle it, which defaults to print a traceback and ignoring the exception.
the messages list. Messages might not be in cache if the message is too old
or the client is participating in high traffic guilds.
If this occurs increase the :attr:`Client.max_messages` attribute
If this occurs increase the :class:`max_messages <Client>` parameter
or use the :func:`on_raw_bulk_message_delete` event instead.
This requires :attr:`Intents.messages` to be enabled.
@ -425,7 +425,7 @@ to handle it, which defaults to print a traceback and ignoring the exception.
Messages might not be in cache if the message is too old
or the client is participating in high traffic guilds.
If this occurs increase the :attr:`Client.max_messages` attribute
If this occurs increase the :class:`max_messages <Client>` parameter
or use the :func:`on_raw_message_edit` event instead.
The following non-exhaustive cases trigger this event:
@ -1078,6 +1078,59 @@ of :class:`enum.Enum`.
.. versionadded:: 2.0
.. class:: UserFlags
Represents Discord User flags.
.. attribute:: staff
The user is a Discord Employee.
.. attribute:: partner
The user is a Discord Partner.
.. attribute:: hypesquad
The user is a HypeSquad Events member.
.. attribute:: bug_hunter
The user is a Bug Hunter.
.. attribute:: mfa_sms
The user has SMS recovery for Multi Factor Authentication enabled.
.. attribute:: premium_promo_dismissed
The user has dismissed the Discord Nitro promotion.
.. attribute:: hypesquad_bravery
The user is a HypeSquad Bravery member.
.. attribute:: hypesquad_brilliance
The user is a HypeSquad Brilliance member.
.. attribute:: hypesquad_balance
The user is a HypeSquad Balance member.
.. attribute:: early_supporter
The user is an Early Supporter.
.. attribute:: team_user
The user is a Team User.
.. attribute:: system
The user is a system user (i.e. represents Discord officially).
.. attribute:: has_unread_urgent_messages
The user has an unready system message.
.. attribute:: bug_hunter_level_2
The user is a Bug Hunter Level 2.
.. attribute:: verified_bot
The user is a Verified Bot.
.. attribute:: verified_bot_developer
The user is an Early Verified Bot Developer.
.. class:: ActivityType
Specifies the type of :class:`Activity`. This is used to check how to
@ -1854,7 +1907,7 @@ of :class:`enum.Enum`.
.. class:: TeamMembershipState
Represents the membership state of a team member retrieved through :func:`Bot.application_info`.
Represents the membership state of a team member retrieved through :func:`Client.application_info`.
.. versionadded:: 1.3
@ -2581,6 +2634,7 @@ Webhook
.. autoclass:: Webhook()
:members:
:inherited-members:
WebhookMessage
~~~~~~~~~~~~~~~~
@ -2597,6 +2651,7 @@ SyncWebhook
.. autoclass:: SyncWebhook()
:members:
:inherited-members:
SyncWebhookMessage
~~~~~~~~~~~~~~~~~~~

2
docs/conf.py
View File

@ -53,7 +53,7 @@ extlinks = {
intersphinx_mapping = {
'py': ('https://docs.python.org/3', None),
'aio': ('https://docs.aiohttp.org/en/stable/', None),
'req': ('http://docs.python-requests.org/en/latest/', 'requests.inv')
'req': ('https://docs.python-requests.org/en/latest/', None)
}
rst_prolog = """

10
docs/ext/commands/api.rst
View File

@ -42,7 +42,7 @@ Event Reference
These events function similar to :ref:`the regular events <discord-api-events>`, except they
are custom to the command extension module.
.. function:: on_command_error(ctx, error)
.. function:: discord.ext.commands.on_command_error(ctx, error)
An error handler that is called when an error is raised
inside a command either through user input error, check
@ -55,7 +55,7 @@ are custom to the command extension module.
:param error: The error that was raised.
:type error: :class:`.CommandError` derived
.. function:: on_command(ctx)
.. function:: discord.ext.commands.on_command(ctx)
An event that is called when a command is found and is about to be invoked.
@ -65,7 +65,7 @@ are custom to the command extension module.
:param ctx: The invocation context.
:type ctx: :class:`.Context`
.. function:: on_command_completion(ctx)
.. function:: discord.ext.commands.on_command_completion(ctx)
An event that is called when a command has completed its invocation.
@ -374,6 +374,9 @@ Exceptions
.. autoexception:: discord.ext.commands.BadUnionArgument
:members:
.. autoexception:: discord.ext.commands.BadLiteralArgument
:members:
.. autoexception:: discord.ext.commands.PrivateMessageOnly
:members:
@ -533,6 +536,7 @@ Exception Hierarchy
- :exc:`~.commands.TooManyFlags`
- :exc:`~.commands.MissingRequiredFlag`
- :exc:`~.commands.BadUnionArgument`
- :exc:`~.commands.BadLiteralArgument`
- :exc:`~.commands.ArgumentParsingError`
- :exc:`~.commands.UnexpectedQuoteError`
- :exc:`~.commands.InvalidEndOfQuotedStringError`

2
docs/ext/commands/commands.rst
View File

@ -761,7 +761,7 @@ When our commands fail to parse we will, by default, receive a noisy error in ``
that an error has happened and has been silently ignored.
In order to handle our errors, we must use something called an error handler. There is a global error handler, called
:func:`on_command_error` which works like any other event in the :ref:`discord-api-events`. This global error handler is
:func:`.on_command_error` which works like any other event in the :ref:`discord-api-events`. This global error handler is
called for every error reached.
Most of the time however, we want to handle an error local to the command itself. Luckily, commands come with local error

2
docs/quickstart.rst
View File

@ -56,7 +56,7 @@ There's a lot going on here, so let's walk you through it step by step.
is the same as the :attr:`Client.user`.
5. Afterwards, we check if the :class:`Message.content` starts with ``'$hello'``. If it does,
then we send a message in the channel it was used in with ``'Hello!'``. This is a basic way of
handling commands, which can be later automated with the :ref:`ext.commands` framework.
handling commands, which can be later automated with the :doc:`./ext/commands/index` framework.
6. Finally, we run the bot with our login token. If you need help getting your token or creating a bot,
look in the :ref:`discord-intro` section.

BIN
docs/requests.inv
View File

Binary file not shown.

2
docs/whats_new.rst
View File

@ -1173,4 +1173,4 @@ Bug Fixes
- Mentions are now triggered normally. This was changed due to the way discord handles it internally.
- Fix issue when a :class:`Message` would attempt to upgrade a :attr:`Message.server` when the channel is
a :class:`Object`.
- Unavailable servers were not being added into cache, this has been corrected.
- Unavailable servers were not being added into cache, this has been corrected.

2
setup.py
View File

@ -36,7 +36,7 @@ with open('README.rst') as f:
extras_require = {
'voice': ['PyNaCl>=1.3.0,<1.5'],
'docs': [
'sphinx==3.5.3',
'sphinx==3.5.4',
'sphinxcontrib_trio==1.1.2',
'sphinxcontrib-websupport',
]