[Guide] Intro & Quickstart guide #9263

AbstractUmbra · 2023-02-25T13:19:26Z

Summary

(Duplicate of #7500 due to contributor inactivity).

This PR will add the Intro and Quickstart guides to the discord.py guide.

Checklist

If code changes were made then they have been tested.
- I have updated the documentation to reflect the changes.
This PR fixes an issue.
This PR adds something new (e.g. new method or parameters).
This PR is a breaking change (e.g. methods or parameters removed/renamed)
This PR is not a code change (e.g. documentation, README, ...)

numbermaniac

A couple of quick grammar nitpicks.

docs/guide/quickstart.rst

ShineyDev

This guide is not an introduction to the library, but a guide to installing the library. You should consider changing the file name to install.rst or similar, and creating a true introduction such as the django overview or similar.

docs/guide/intro.rst

IAmTomahawkx

Mostly good, a couple of newer developments in discord that should be updated though

docs/guide/quickstart.rst

docs/guide/intro.rst

docs/guide/quickstart.rst

docs/guide/intro.rst

docs/guide/quickstart.rst

tailoric · 2024-01-17T15:11:50Z

As mentioned some time ago in the #docs channel on the discord server by me.
Could it be possible to also explain, or at least mention, the command line commands of discord.py:

python -m discord newbot
python -m discord newcog

I've noticed that they are never mentioned in the documentation at all (unless I really missed them) and many people don't even know about these helpful features for setting up the base skeleton of both.
It could be nice to tell in the introduction about at least the newbot command since it sets up a good "boilerplate" to start from.
The newcog command may be better suited inside the Cogs guide but I think it would be helpful to give more awareness to both of them in the guides.

Co-authored-by: numbermaniac <5206120+numbermaniac@users.noreply.github.com>

Co-authored-by: Riley Miļeško <30989490+ShineyDev@users.noreply.github.com>

ShineyDev

Since the content has been reviewed by several others by now I'll just restate that the files should be renamed. A guide/intro should not tell me how to install a library, consider renaming to guide/install[ation]. This also makes space for guide/quickstart to be renamed to guide/intro[duction].

AbstractUmbra · 2024-02-03T19:59:05Z

Since the content has been reviewed by several others by now I'll just restate that the files should be renamed. A guide/intro should not tell me how to install a library, consider renaming to guide/install[ation]. This also makes space for guide/quickstart to be renamed to guide/intro[duction].

I personally agree with this and will rename these files appropriately. If there are issues we can always revert.

ika2kki

left a few comments below.
happy with the content so far

docs/guide/installation.rst

docs/guide/introduction.rst

ShineyDev

LGTM.

No767

As per usual, I left some of my suggestions and thoughts down in this review. The section "A Simple Bot" (in docs/guide/introduction.rst) doesn't flow nicely and it was really hard to read in order to understand what it was supposed to be guiding me through.

docs/guide/installation.rst

docs/guide/introduction.rst

bijij · 2024-04-13T14:40:05Z

docs/guide/installation.rst

+
+    python3 -m pip install -U discord.py
+
+On Windows systems, you can use the following command instead.


Suggested change

On Windows systems, you can use the following command instead.

On Windows, you can use the following command instead.

bijij · 2024-04-13T14:40:13Z

docs/guide/installation.rst

+Primer
+-------------
+
+On Unix systems you can run the following command to install discord.py from PyPI.


Suggested change

On Unix systems you can run the following command to install discord.py from PyPI.

On Unix-based systems you can run the following command to install discord.py from PyPI.

bijij · 2024-04-13T14:54:56Z

docs/guide/installation.rst

+Linux systems may need to install additional dependencies via your package manager to get full voice support:-
+
+.. tab:: Debian/Ubuntu
+
+    .. code-block:: shell
+
+        $ sudo apt install libffi-dev libsodium-dev python3-dev
+
+.. tab:: Fedora/CentOS
+
+    .. code-block:: shell
+
+        $ sudo dnf install libffi-devel libsodium-devel python3-devel
+
+.. tab:: Arch Linux
+
+    .. code-block:: shell
+
+        $ pacman -Syu libsodium libffi
+
+For other distributions, please use your package manager to find libraries for ``libffi``, ``libsodium``, and the Python 3 development headers.


Suggested change

Linux systems may need to install additional dependencies via your package manager to get full voice support:-

.. tab:: Debian/Ubuntu

.. code-block:: shell

$ sudo apt install libffi-dev libsodium-dev python3-dev

.. tab:: Fedora/CentOS

.. code-block:: shell

$ sudo dnf install libffi-devel libsodium-devel python3-devel

.. tab:: Arch Linux

.. code-block:: shell

$ pacman -Syu libsodium libffi

For other distributions, please use your package manager to find libraries for ``libffi``, ``libsodium``, and the Python 3 development headers.

.. note::

You may need to install additional libraries to enable voice support on Linux, below are the commands for some popular distributions.

.. tab:: Debian/Ubuntu

.. code-block:: shell

$ sudo apt install libffi-dev libsodium-dev python3-dev

.. tab:: Fedora/CentOS

.. code-block:: shell

$ sudo dnf install libffi-devel libsodium-devel python3-devel

.. tab:: Arch Linux

.. code-block:: shell

$ pacman -Syu libsodium libffi

For other distributions, please use your package manager to find libraries for ``libffi``, ``libsodium``, and the Python 3 development headers.

bijij · 2024-04-13T14:56:21Z

docs/guide/installation.rst

+    .. code-block:: shell
+
+        $ cd your_bot_source
+        $ python3 -m venv .venv


This probably needs to be distro specific.

I don't understand why creating a venv would be distro specific here. Could you explain your comment in more detail? We can have a note that says for windows systems to use the py launcher to gently remind users for that.

bijij · 2024-04-13T14:56:45Z

docs/guide/installation.rst

+
+    The ``.venv`` argument is the output folder of the virtual environment, this can be named anything but be sure to remember it.
+
+2. Activate the virtual environment:


This should be tabs too.

bijij · 2024-04-13T14:57:46Z

docs/guide/installation.rst

+Next Steps
+-----------
+
+Now that you've installed discord.py, the next step is to begin making your bot application. See :ref:`_guide_intro` for further getting started steps.


Suggested change

Now that you've installed discord.py, the next step is to begin making your bot application. See :ref:`_guide_intro` for further getting started steps.

Now that you've installed discord.py, the next step is to begin making your application. See :ref:`_guide_intro` for further getting started steps.

bijij · 2024-04-13T14:59:48Z

docs/guide/introduction.rst

+
+.. warning::
+
+    If you accidentally use the ``Client Secret`` for your bot token, it's **NOT** what you are looking for - you need the bot **Token**, which has a different format.


I'd probably reword this, Maybe "Ensure you don't use the Client Secret in place of your token, these are not the same thing and ..."

bijij · 2024-04-13T15:03:49Z

docs/guide/introduction.rst

+    async def apples(ctx: commands.Context, amount: int) -> None:
+        await ctx.send(f"Hello, I would like {amount} apples please!")
+
+Here's where our commands will be defined. We use the :meth:`@bot.command() <ext.commands.Bot.command>` decorator to flag this function as a command.


Where's here?

bijij · 2024-04-13T15:05:31Z

docs/guide/introduction.rst

+Here's where our commands will be defined. We use the :meth:`@bot.command() <ext.commands.Bot.command>` decorator to flag this function as a command.
+This creates a command ``!apples`` that we can type into a channel, and the bot will respond with the given amount of applies in a predefined sentence.. A few key features:
+
+- :class:`~ext.commands.Context` refers to the command invocation context - this includes the :attr:`~ext.commands.Context.channel`, command :attr:`~ext.commands.Context.author`, :attr:`~ext.commands.Context.message` and more.


I would reword the "this includes" section to use "such as ..." rather than "... and more".

bijij · 2024-04-13T15:06:52Z

docs/guide/introduction.rst

+
+    TOKEN = "your bot token here"
+
+This is the final step, you put your bot token here, save and run the file and the bot will start up.


nowhere in this do I see Bot.run explicitly being called. you'll need to add that.

bijij · 2024-04-13T15:07:55Z

docs/guide/introduction.rst

+
+Activate the virtual environment (if you made one):
+
+.. code-block:: shell


Again, use tabs.

bijij · 2024-04-13T15:10:00Z

docs/images/discord_client_secret_big_nono.png

big nono dot png

AbstractUmbra marked this pull request as ready for review February 25, 2023 13:45

numbermaniac reviewed Feb 27, 2023

View reviewed changes

docs/guide/quickstart.rst Outdated Show resolved Hide resolved

docs/guide/quickstart.rst Outdated Show resolved Hide resolved

docs/guide/quickstart.rst Outdated Show resolved Hide resolved

ShineyDev suggested changes Mar 6, 2023

View reviewed changes

docs/guide/intro.rst Outdated Show resolved Hide resolved

docs/guide/intro.rst Outdated Show resolved Hide resolved

docs/guide/intro.rst Outdated Show resolved Hide resolved

docs/guide/intro.rst Outdated Show resolved Hide resolved

docs/guide/intro.rst Outdated Show resolved Hide resolved

IAmTomahawkx suggested changes Sep 11, 2023

View reviewed changes

docs/guide/quickstart.rst Outdated Show resolved Hide resolved

docs/guide/quickstart.rst Outdated Show resolved Hide resolved

docs/guide/quickstart.rst Outdated Show resolved Hide resolved

Rapptz requested changes Sep 14, 2023

View reviewed changes

Gobot1234 reviewed Sep 14, 2023

View reviewed changes

Gobot1234 mentioned this pull request Sep 14, 2023

[reloaded] Add inline-tabs extension #9563

Merged

6 tasks

XuaTheGrate and others added 9 commits February 3, 2024 13:24

moving intro guide

cd29da0

fix build errors

550459f

show token after copy changes

1b836d4

remove needless prose

932f4d0

Update docs/guide/quickstart.rst

7bb3a9f

Co-authored-by: numbermaniac <5206120+numbermaniac@users.noreply.github.com>

Update docs/guide/quickstart.rst

ed32f59

Co-authored-by: numbermaniac <5206120+numbermaniac@users.noreply.github.com>

Update docs/guide/quickstart.rst

a1f6a39

Co-authored-by: numbermaniac <5206120+numbermaniac@users.noreply.github.com>

Apply suggestions from code review

510983c

Co-authored-by: Riley Miļeško <30989490+ShineyDev@users.noreply.github.com>

update quickstart guide to reflect Intents changes

1a5cf3f

AbstractUmbra force-pushed the docs/guide-introduction branch from 14e85d1 to 1a5cf3f Compare February 3, 2024 13:25

AbstractUmbra added 3 commits February 3, 2024 13:29

apply suggestions

7b3ed8a

apply suggestions

abbfb7b

apply link changes and step corrections

1d5f14f

AbstractUmbra requested review from Gobot1234, ShineyDev, IAmTomahawkx and Willy-C February 3, 2024 14:21

AbstractUmbra added 2 commits February 3, 2024 14:55

add section on newbot/newcog convenience methods

c965a16

Fix line break

edefab0

AbstractUmbra requested a review from numbermaniac February 3, 2024 15:19

fix bad link

5e2c820

ShineyDev suggested changes Feb 3, 2024

View reviewed changes

Rename to a saner startup

3c273b3

ika2kki reviewed Feb 3, 2024

View reviewed changes

AbstractUmbra added 2 commits February 4, 2024 14:57

use sphinx inline tabs

2b23d84

apply suggestion

27c0794

ShineyDev approved these changes Feb 4, 2024

View reviewed changes

No767 suggested changes Feb 7, 2024

View reviewed changes

AbstractUmbra added 3 commits February 11, 2024 20:38

apply suggestions

b56b3bd

fix page link

48b0d51

add missing dependency

3d9df90

bijij reviewed Apr 13, 2024

View reviewed changes

bijij suggested changes Apr 13, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[Guide] Intro & Quickstart guide #9263

[Guide] Intro & Quickstart guide #9263

AbstractUmbra commented Feb 25, 2023

numbermaniac left a comment

ShineyDev left a comment

IAmTomahawkx left a comment

tailoric commented Jan 17, 2024

ShineyDev left a comment

AbstractUmbra commented Feb 3, 2024

ika2kki left a comment

ShineyDev left a comment

No767 left a comment

bijij Apr 13, 2024

bijij Apr 13, 2024

bijij Apr 13, 2024

bijij Apr 13, 2024

No767 Apr 13, 2024

bijij Apr 13, 2024

bijij Apr 13, 2024

bijij Apr 13, 2024

bijij Apr 13, 2024

bijij Apr 13, 2024

bijij Apr 13, 2024

bijij Apr 13, 2024

bijij Apr 13, 2024


		python3 -m pip install -U discord.py

		On Windows systems, you can use the following command instead.

	On Windows systems, you can use the following command instead.
	On Windows, you can use the following command instead.

	On Unix systems you can run the following command to install discord.py from PyPI.
	On Unix-based systems you can run the following command to install discord.py from PyPI.


		The ``.venv`` argument is the output folder of the virtual environment, this can be named anything but be sure to remember it.

		2. Activate the virtual environment:

	Now that you've installed discord.py, the next step is to begin making your bot application. See :ref:`_guide_intro` for further getting started steps.
	Now that you've installed discord.py, the next step is to begin making your application. See :ref:`_guide_intro` for further getting started steps.


		.. warning::

		If you accidentally use the ``Client Secret`` for your bot token, it's NOT what you are looking for - you need the bot Token, which has a different format.


		TOKEN = "your bot token here"

		This is the final step, you put your bot token here, save and run the file and the bot will start up.


		Activate the virtual environment (if you made one):

		.. code-block:: shell

[Guide] Intro & Quickstart guide #9263

Are you sure you want to change the base?

[Guide] Intro & Quickstart guide #9263

Conversation

AbstractUmbra commented Feb 25, 2023

Summary

Checklist

numbermaniac left a comment

Choose a reason for hiding this comment

ShineyDev left a comment

Choose a reason for hiding this comment

IAmTomahawkx left a comment

Choose a reason for hiding this comment

tailoric commented Jan 17, 2024

ShineyDev left a comment

Choose a reason for hiding this comment

AbstractUmbra commented Feb 3, 2024

ika2kki left a comment

Choose a reason for hiding this comment

ShineyDev left a comment

Choose a reason for hiding this comment

No767 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment