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

Add intersphinx

Browse Source
This commit is contained in:
Tobotimus
2018-01-06 17:21:56 -05:00
committed by Rapptz
parent 0ef866a704
commit 3112e1c17e
37 changed files with 267 additions and 268 deletions
Download Patch File Download Diff File Expand all files Collapse all files

62
docs/api.rst
View File

@ -94,7 +94,7 @@ to handle it, which defaults to print a traceback and ignoring the exception.
All the events must be a |corourl|_. If they aren't, then you might get unexpected
errors. In order to turn a function into a coroutine they must either be ``async def``
functions or in 3.4 decorated with ``@asyncio.coroutine``.
functions or in 3.4 decorated with :func:`asyncio.coroutine`.
The following two functions are examples of coroutine functions: ::
@ -172,7 +172,7 @@ to handle it, which defaults to print a traceback and ignoring the exception.
WebSocket. The voice WebSocket will not trigger this event.
:param msg: The message passed in from the WebSocket library.
Could be ``bytes`` for a binary message or ``str``
Could be :class:`bytes` for a binary message or :class:`str`
for a regular message.
.. function:: on_socket_raw_send(payload)
@ -190,8 +190,8 @@ to handle it, which defaults to print a traceback and ignoring the exception.
WebSocket. The voice WebSocket will not trigger this event.
:param payload: The message that is about to be passed on to the
WebSocket library. It can be ``bytes`` to denote a binary
message or ``str`` to denote a regular text message.
WebSocket library. It can be :class:`bytes` to denote a binary
message or :class:`str` to denote a regular text message.
.. function:: on_typing(channel, user, when)
@ -1359,14 +1359,14 @@ Certain utilities make working with async iterators easier, detailed below.
|coro|
Flattens the async iterator into a ``list`` with all the elements.
Flattens the async iterator into a :class:`list` with all the elements.
:return: A list of every element in the async iterator.
:rtype: list
.. method:: map(func)
This is similar to the built-in ``map`` function. Another
This is similar to the built-in :func:`map <python:map>` function. Another
:class:`AsyncIterator` is returned that executes the function on
every element it is iterating over. This function can either be a
regular function or a coroutine.
@ -1384,7 +1384,7 @@ Certain utilities make working with async iterators easier, detailed below.
.. method:: filter(predicate)
This is similar to the built-in ``filter`` function. Another
This is similar to the built-in :func:`filter <python:filter>` function. Another
:class:`AsyncIterator` is returned that filters over the original
async iterator. This predicate can be a regular function or a coroutine.
@ -1474,15 +1474,15 @@ this goal, it must make use of a couple of data classes that aid in this goal.
.. attribute:: name
*str* – A name of something.
:class:`str` – A name of something.
.. attribute:: icon
*str* – A guild's icon hash. See also :attr:`Guild.icon`.
:class:`str` – A guild's icon hash. See also :attr:`Guild.icon`.
.. attribute:: splash
*str* – The guild's invite splash hash. See also :attr:`Guild.splash`.
:class:`str` – The guild's invite splash hash. See also :attr:`Guild.splash`.
.. attribute:: owner
@ -1512,15 +1512,15 @@ this goal, it must make use of a couple of data classes that aid in this goal.
.. attribute:: afk_timeout
*int* – The guild's AFK timeout. See :attr:`Guild.afk_timeout`.
:class:`int` – The guild's AFK timeout. See :attr:`Guild.afk_timeout`.
.. attribute:: mfa_level
*int* - The guild's MFA level. See :attr:`Guild.mfa_level`.
:class:`int` - The guild's MFA level. See :attr:`Guild.mfa_level`.
.. attribute:: widget_enabled
*bool* – The guild's widget has been enabled or disabled.
:class:`bool` – The guild's widget has been enabled or disabled.
.. attribute:: widget_channel
@ -1543,37 +1543,37 @@ this goal, it must make use of a couple of data classes that aid in this goal.
.. attribute:: default_message_notifications
*int* – The guild's default message notification setting.
:class:`int` – The guild's default message notification setting.
.. attribute:: vanity_url_code
*str* – The guild's vanity URL.
:class:`str` – The guild's vanity URL.
See also :meth:`Guild.vanity_invite` and :meth:`Guild.change_vanity_invite`.
.. attribute:: position
*int* – The position of a :class:`Role` or :class:`abc.GuildChannel`.
:class:`int` – The position of a :class:`Role` or :class:`abc.GuildChannel`.
.. attribute:: type
*Union[int, str]* – The type of channel or channel permission overwrite.
If the type is an ``int``, then it is a type of channel which can be either
If the type is an :class:`int`, then it is a type of channel which can be either
``0`` to indicate a text channel or ``1`` to indicate a voice channel.
If the type is a ``str``, then it is a type of permission overwrite which
If the type is a :class:`str`, then it is a type of permission overwrite which
can be either ``'role'`` or ``'member'``.
.. attribute:: topic
*str* – The topic of a :class:`TextChannel`.
:class:`str` – The topic of a :class:`TextChannel`.
See also :attr:`TextChannel.topic`.
.. attribute:: bitrate
*int* – The bitrate of a :class:`VoiceChannel`.
:class:`int` – The bitrate of a :class:`VoiceChannel`.
See also :attr:`VoiceChannel.bitrate`.
@ -1605,13 +1605,13 @@ this goal, it must make use of a couple of data classes that aid in this goal.
.. attribute:: deaf
*bool* – Whether the member is being server deafened.
:class:`bool` – Whether the member is being server deafened.
See also :attr:`VoiceState.deaf`.
.. attribute:: mute
*bool* – Whether the member is being server muted.
:class:`bool` – Whether the member is being server muted.
See also :attr:`VoiceState.mute`.
@ -1630,19 +1630,19 @@ this goal, it must make use of a couple of data classes that aid in this goal.
.. attribute:: hoist
*bool* – Whether the role is being hoisted or not.
:class:`bool` – Whether the role is being hoisted or not.
See also :attr:`Role.hoist`
.. attribute:: mentionable
*bool* – Whether the role is mentionable or not.
:class:`bool` – Whether the role is mentionable or not.
See also :attr:`Role.mentionable`
.. attribute:: code
*str* – The invite's code.
:class:`str` – The invite's code.
See also :attr:`Invite.code`
@ -1661,25 +1661,25 @@ this goal, it must make use of a couple of data classes that aid in this goal.
.. attribute:: max_uses
*int* – The invite's max uses.
:class:`int` – The invite's max uses.
See also :attr:`Invite.max_uses`.
.. attribute:: uses
*int* – The invite's current uses.
:class:`int` – The invite's current uses.
See also :attr:`Invite.uses`.
.. attribute:: max_age
*int* – The invite's max age in seconds.
:class:`int` – The invite's max age in seconds.
See also :attr:`Invite.max_age`.
.. attribute:: temporary
*bool* – If the invite is a temporary invite.
:class:`bool` – If the invite is a temporary invite.
See also :attr:`Invite.temporary`.
@ -1690,11 +1690,11 @@ this goal, it must make use of a couple of data classes that aid in this goal.
.. attribute:: id
*int* – The ID of the object being changed.
:class:`int` – The ID of the object being changed.
.. attribute:: avatar
*str* – The avatar hash of a member.
:class:`str` – The avatar hash of a member.
See also :attr:`User.avatar`.

4
docs/conf.py
View File

@ -35,6 +35,7 @@ sys.path.append(os.path.abspath('extensions'))
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.extlinks',
'sphinx.ext.intersphinx',
'sphinxcontrib.asyncio',
'details'
]
@ -50,6 +51,9 @@ extlinks = {
'issue': ('https://github.com/Rapptz/discord.py/issues/%s', 'issue '),
}
# Links used for cross-referencing stuff in other documentation
intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}
rst_prolog = """
.. |coro| replace:: This function is a |corourl|_.
.. |maybecoro| replace:: This function *could be a* |corourl|_.

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

@ -189,7 +189,7 @@ Converters come in a few flavours:
- A regular callable object that takes an argument as a sole parameter and returns a different type.
- These range from your own function, to something like ``bool`` or ``int``.
- These range from your own function, to something like :class:`bool` or :class:`int`.
- A custom class that inherits from :class:`~ext.commands.Converter`.

13
docs/faq.rst
View File

@ -18,7 +18,7 @@ Questions regarding coroutines and asyncio belong here.
I get a SyntaxError around the word ``async``\! What should I do?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This ``SyntaxError`` happens because you're using a Python version lower than 3.5. Python 3.4 uses ``@asyncio.coroutine`` and
This :exc:`SyntaxError` happens because you're using a Python version lower than 3.5. Python 3.4 uses ``@asyncio.coroutine`` and
``yield from`` instead of ``async def`` and ``await``.
Thus you must do the following instead: ::
@ -59,7 +59,7 @@ despair however, because not all forms of blocking are bad! Using blocking calls
sure that you don't excessively block functions. Remember, if you block for too long then your bot will freeze since it has
not stopped the function's execution at that point to do other things.
A common source of blocking for too long is something like ``time.sleep(n)``. Don't do that. Use ``asyncio.sleep(n)``
A common source of blocking for too long is something like :func:`time.sleep`. Don't do that. Use :func:`asyncio.sleep`
instead. Similar to this example: ::
# bad
@ -69,7 +69,7 @@ instead. Similar to this example: ::
await asyncio.sleep(10)
Another common source of blocking for too long is using HTTP requests with the famous module ``requests``. While ``requests``
is an amazing module for non-asynchronous programming, it is not a good choice for ``asyncio`` because certain requests can
is an amazing module for non-asynchronous programming, it is not a good choice for :mod:`asyncio` because certain requests can
block the event loop too long. Instead, use the ``aiohttp`` library which is installed on the side with this library.
Consider the following example: ::
@ -135,7 +135,7 @@ To upload multiple files, you can use the ``files`` keyword argument instead of
await channel.send(files=my_files)
If you want to upload something from a URL, you will have to use an HTTP request using ``aiohttp``
and then pass an ``io.BytesIO`` instance to :class:`File` like so:
and then pass an :class:`io.BytesIO` instance to :class:`File` like so:
.. code-block:: python3
@ -192,8 +192,7 @@ that wraps up a couple of aspects.
The first gotcha that you must be aware of is that calling a coroutine is not a thread-safe operation. Since we are
technically in another thread, we must take caution in calling thread-safe operations so things do not bug out. Luckily for
us, ``asyncio`` comes with a ``asyncio.run_coroutine_threadsafe``
`function <https://docs.python.org/3.5/library/asyncio-task.html#asyncio.run_coroutine_threadsafe>`_ that allows us to call
us, :mod:`asyncio` comes with a :func:`asyncio.run_coroutine_threadsafe` function that allows us to call
a coroutine from another thread.
.. warning::
@ -201,7 +200,7 @@ a coroutine from another thread.
This function is only part of 3.5.1+ and 3.4.4+. If you are not using these Python versions then use
``discord.compat.run_coroutine_threadsafe``.
However, this function returns a ``concurrent.Future`` and to actually call it we have to fetch its result. Putting all of
However, this function returns a :class:`concurrent.Future` and to actually call it we have to fetch its result. Putting all of
this together we can do the following: ::
def my_after(error):

8
docs/logging.rst
View File

@ -4,7 +4,7 @@
Setting Up Logging
===================
*discord.py* logs errors and debug information via the `logging`_ python
*discord.py* logs errors and debug information via the :mod:`logging` python
module. It is strongly recommended that the logging module is
configured, as no errors or warnings will be output if it is not set up.
Configuration of the ``logging`` module can be as simple as::
@ -21,7 +21,7 @@ The optional ``level`` argument specifies what level of events to log
out and can any of ``CRITICAL``, ``ERROR``, ``WARNING``, ``INFO``, and
``DEBUG`` and if not specified defaults to ``WARNING``.
More advance setups are possible with the ``logging`` module. To for
More advance setups are possible with the :mod:`logging` module. To for
example write the logs to a file called ``discord.log`` instead of
outputting them to to the console the following snippet can be used::
@ -41,6 +41,4 @@ stdout of your program.
For more information, check the documentation and tutorial of the
`logging`_ module.
.. _logging: https://docs.python.org/2/library/logging.html
:mod:`logging` module.

4
docs/migrating.rst
View File

@ -22,7 +22,7 @@ Below are major model changes that have happened in v1.0
Snowflakes are int
~~~~~~~~~~~~~~~~~~~~
Before v1.0, all snowflakes (the ``id`` attribute) were strings. This has been changed to ``int``.
Before v1.0, all snowflakes (the ``id`` attribute) were strings. This has been changed to :class:`int`.
Quick example: ::
@ -657,7 +657,7 @@ For example, to wait for a reaction: ::
# use user and reaction
Since this function now can return multiple arguments, the ``timeout`` parameter will now raise a ``asyncio.TimeoutError``
Since this function now can return multiple arguments, the ``timeout`` parameter will now raise a :exc:`asyncio.TimeoutError`
when reached instead of setting the return to ``None``. For example:
.. code-block:: python3

2
docs/migrating_to_async.rst
View File

@ -142,7 +142,7 @@ Some examples of previously valid behaviour that is now invalid
if client.servers[0].name == "test":
# do something
Since they are no longer ``list``\s, they no longer support indexing or any operation other than iterating.
Since they are no longer :obj:`list`\s, they no longer support indexing or any operation other than iterating.
In order to get the old behaviour you should explicitly cast it to a list.
.. code-block:: python3