diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/api.rst | 62 | ||||
| -rw-r--r-- | docs/conf.py | 4 | ||||
| -rw-r--r-- | docs/ext/commands/commands.rst | 2 | ||||
| -rw-r--r-- | docs/faq.rst | 13 | ||||
| -rw-r--r-- | docs/logging.rst | 8 | ||||
| -rw-r--r-- | docs/migrating.rst | 4 | ||||
| -rw-r--r-- | docs/migrating_to_async.rst | 2 |
7 files changed, 48 insertions, 47 deletions
diff --git a/docs/api.rst b/docs/api.rst index 29b2e8d4..16254a75 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -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`. diff --git a/docs/conf.py b/docs/conf.py index f0af548f..dd486917 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -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|_. diff --git a/docs/ext/commands/commands.rst b/docs/ext/commands/commands.rst index dc8d7e73..d1957438 100644 --- a/docs/ext/commands/commands.rst +++ b/docs/ext/commands/commands.rst @@ -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`. diff --git a/docs/faq.rst b/docs/faq.rst index bc01eabe..57daa471 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -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): diff --git a/docs/logging.rst b/docs/logging.rst index 03955752..4724d02e 100644 --- a/docs/logging.rst +++ b/docs/logging.rst @@ -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. diff --git a/docs/migrating.rst b/docs/migrating.rst index 57d4f3a6..099872f5 100644 --- a/docs/migrating.rst +++ b/docs/migrating.rst @@ -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 diff --git a/docs/migrating_to_async.rst b/docs/migrating_to_async.rst index 109ad409..1853321c 100644 --- a/docs/migrating_to_async.rst +++ b/docs/migrating_to_async.rst @@ -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 |