Refactoring and improvements to contributing docs

pydis_site/apps/content/resources/guides/pydis-guides/contributing.md

@@ -94,11 +94,7 @@ GitHub is a website based on Git that stores project files in the cloud. We use
 
 *Note: Members of the Python Discord staff can create feature branches directly on the repo without forking it.*
 
-Check out our [**guide on forking a GitHub repo**](./forking-repository/).
-
-Now that you have your own fork you need to be able to make changes to the code. You can clone the repo to your local machine, commit changes to it there, then push those changes to GitHub.
-
-Check out our [**guide on cloning a GitHub repo**](./cloning-repository/).
+Check out our [**guide on forking and cloning a GitHub repository**](./forking-and-cloning-repository/).
 
 ### 2. Set up the project
 You have the source code on your local computer, now how do you actually run it? We have detailed guides on setting up the environment for each of our main projects:

pydis_site/apps/content/resources/guides/pydis-guides/contributing/bot.md

@@ -4,66 +4,42 @@ description: A guide to setting up and configuring Bot.
 icon: fab fa-github
 toc: 3
 ---
-The purpose of this guide is to get you a running local version of [the Python bot](https://github.com/python-discord/bot).
-You should have already forked the repository and cloned it to your local machine. If not, check out our [detailed walkthrough](../#1-fork-and-clone-the-repo).
+This guide will walk you through setting up and running [the Python bot](https://github.com/python-discord/bot) locally,
+and get you ready to contribute to it.
 
-This page will focus on the quickest steps one can take, with mentions of alternatives afterwards.
+It focuses on the recommended setup using Docker, though alternative options are linked where relevant.
 
 ---
+
 ## Setting up the project
 
-### Setup Project Dependencies
-Below are the dependencies you **must** have installed to get started with the bot.
-
-1. Make sure you have [Python 3.14](https://www.python.org/downloads/) installed. uv [can also be used to](https://docs.astral.sh/uv/guides/install-python/#installing-python) install Python, if desired.
-2. [Install uv](https://github.com/astral-sh/uv#installation).
-3. [Install the project's dependencies](../installing-project-dependencies).
-4. Docker.
-
-<div class="card">
-    <button type="button" class="card-header collapsible">
-        <span class="card-header-title subtitle is-6 my-2 ml-2">Getting started with Docker</span>
-        <span class="card-header-icon">
-            <i class="fas fa-fw fa-angle-down title is-5" aria-hidden="true"></i>
-        </span>
-    </button>
-    <div class="collapsible-content collapsed">
-        <div class="card-content">
-            The requirements for Docker are:
-            <ul>
-                <li><a href="https://docs.docker.com/install">Docker CE</a></li>
-                <li>Docker Compose. If you're using macOS and Windows, this already comes bundled with the previous installation. Otherwise, you can download it either from the <a href="https://docs.docker.com/compose/install">website</a>, or by running <code>pip install docker-compose</code>.</li>
-            </ul>
-            <p class="notification is-warning">If you get any Docker related errors, reference the <a href="../docker#possible-issues">Possible Issue</a> section of the Docker page.</p>
-        </div>
-    </div>
-</div>
-<br>
+To start, ensure you have forked and cloned the [bot repository](https://github.com/python-discord/bot) to your local machine. For help with this, check out our [detailed guide](../forking-and-cloning).
+
+### Set Up Project Dependencies
+The following are needed to run the bot:
+
+1. uv: See the [uv installation guide](https://docs.astral.sh/uv/getting-started/installation/).
+2. [Python 3.14](https://www.python.org/downloads/): This can be installed [using uv](https://docs.astral.sh/uv/guides/install-python/#installing-python).
+3. Project Dependencies: Install by running `uv sync` in the command line from the root directory of the cloned repository.
+4. Docker. See [our docker guide](../docker).
 
 ### Set Up a Test Server
-The Python bot is tightly coupled with the Python Discord server, so to have a functional version of the bot you need a server with channels it can use.
-It's possible to set the bot to use a single channel for all cogs, but that will cause extreme spam and will be difficult to work with.
+The Python bot is tightly coupled with the Python Discord server, so the bot expects the existence of certain
+channels, roles, and other server configurations to be able to run.
 
-You can start your own server and set up channels as you see fit, but for your convenience we have a template for a development server you can use: [https://discord.new/zmHtscpYN9E3](https://discord.new/zmHtscpYN9E3).
+It is highly recommended to use our [server template](https://discord.new/zmHtscpYN9E3),
+as it configures most of this for you.
 
-Keep in mind that this is not an exact mirror of the Python server, but a reduced version for testing purposes.
-The channels there are mostly the ones needed by the bot.
----
+This is not an exact mirror of the Python server, but a reduced version for testing purposes.
 
 ### Set Up a Bot Account
 You will need your own bot account on Discord to test your changes to the bot.
-See [here](../creating-bot-account) for help with setting up a bot account. Once you have a bot account, invite it to the test server you created in the previous section.
+See [our guide](../creating-bot-account) for help with setting up a bot account, and inviting it to your server.
 
-#### Privileged Intents
+If you want to use an existing test bot account, ensure that:
 
-It is necessary to explicitly request that your Discord bot receives certain gateway events.
-The Python bot requires `Server Member Intent` and `Message Content Intent` to function.
-In order to enable it, visit the [Developer Portal](https://discord.com/developers/applications/) (from where you copied your bot's login token) and scroll down to the `Privileged Gateway Intents` section.
-The `Presence Intent` is not necessary and can be left disabled.
-
-If your bot fails to start with a `PrivilegedIntentsRequired` exception, this indicates that the required intents were not enabled.
-
----
+- It has the `Message Content Intent` and `Server Members Intent` intents enabled.
+- It was invited to your server with the `bot` scope and `Administrator` permission.
 
 ### Configure the Bot
 You now have both the bot's code and a server to run it on. It's time for you to connect the two by setting the bot's configuration.
@@ -73,25 +49,22 @@ Both `.env` and `.env.server` files we talk about below are ignored by git, so t
 #### .env
 This file will contain sensitive information such as your bot's token, do not share it with anybody!
 
-To start, create a `.env` file in the project root with the below content.
+Create a file called `.env` in the project root with the below content.
 
 ```text
 BOT_TOKEN=YourDiscordBotTokenHere
 GUILD_ID=YourDiscordTestServerIdHere
-BOT_PREFIX=YourDesiredPrefixHere
 ```
 See [here](../creating-bot-account) for help with obtaining the bot token, and [here](../obtaining-discord-ids#guild-id) for help with obtaining the guild's ID.
 
-Other values will be added to your `.env` over time as you need to interact with other parts of the bot, but those are not needed for a basic setup. For a full list of support values see the ENV file option [appendix](#appendix-full-env-file-options)
+This is all that is needed for a basic setup. See the [appendix](#appendix-full-env-file-options) for a full list of supported available variables.
 
 #### .env.server
 All server related configuration values are saved in this file, which also needs to be at the root directory of the project.
 
 We provide a script to automatically generate a server config.
 **Note**: The script **only** works with servers created with the template mentioned above.
 
-If you want to setup the bot from an existing guild read out [manual configuration guide](../bot-extended-configuration-options#manual-constants-configuration). This is far more complicated and time consuming.
-
 Running the below command will use the `BOT_TOKEN` and `GUILD_ID` from the `.env` file you created above to download all of the relevant IDs from the template guild into your `.env.server`
 
 **Note**: This script will overwrite the `.env.server` file. We suggest you put any configuration not generated by this script in to `.env` instead
@@ -102,33 +75,17 @@ $ uv run task configure
 Once the script has finished running, you'll notice the creation of a new file called `.env.server` at your project's root directory.
 This file will contain the extracted IDs from your server which are necessary for your bot to run.
 
-**Congratulations**, you have finished the configuration and can now [run your bot](#run-it).
-
+If you want to setup the bot from an existing guild read our [manual configuration guide](../bot-extended-configuration-options#manual-constants-configuration). This is far more complicated and time consuming.
 
-<div class="card">
-    <button type="button" class="card-header collapsible">
-        <span class="card-header-title subtitle is-6 my-2 ml-2">Why do you need a separate config file?</span>
-        <span class="card-header-icon">
-            <i class="fas fa-fw fa-angle-down title is-5" aria-hidden="true"></i>
-        </span>
-    </button>
-    <div class="collapsible-content collapsed">
-        <div class="card-content">
-            While it's technically possible to edit the values in <code>constants.py</code> to match your server, it is heavily discouraged.
-            This file's purpose is to provide the configurations the Python bot needs to run in the Python server in production, and should remain as such.
-            In contrast, the <code>.env.server</code> file can remain in your local copy of the code, and will be ignored by commits via the project's <code>.gitignore</code>.
-        </div>
-    </div>
-</div>
-<br>
+---
 
+**Congratulations**, you have finished the configuration and can now [run your bot](#run-it).
 
 ### Run it!
 #### With Docker
-You are now almost ready to run the Python bot. The simplest way to do so is with Docker.
-
+You are now ready to run the Python bot. The simplest way to do so is with Docker.
 
-With all of the above setup, you can run the project with `docker compose up`. This will start the bot and all required services! Enter your server and type `!help` (or whatever prefix you chose instead of `!`) to see the bot in action!
+With all of the above setup, you can run the project with `docker compose up`. This will start the bot and all required services! Enter your server and type `!help` to see the bot in action!
 
 Some other useful docker commands are as follows:
 
@@ -137,6 +94,8 @@ Some other useful docker commands are as follows:
 
 Your bot is now running, all inside Docker.
 
+#### Without Docker
+
 **Note**: If you want to read about how to make debugging with an IDE a easier, or for additional running methods, check out our [extended configuration guide](../bot-extended-configuration-options).
 
 ---

pydis_site/apps/content/resources/guides/pydis-guides/contributing/creating-bot-account.md

@@ -3,15 +3,14 @@ title: Setting up a Bot Account
 description: How to set up a bot account.
 icon: fab fa-discord
 ---
-1. Go to the [Discord Developers Portal](https://discordapp.com/developers/applications/).
-2. Click on the `New Application` button, enter your desired bot name, and click `Create`.
-3. In your new application, go to the `Bot` tab, click `Add Bot`, and confirm `Yes, do it!`
-4. Change your bot's `Public Bot` setting off so only you can invite it, save, and then get your **Bot Token** with the `Copy` button.
-> **Note:** **DO NOT** post your bot token anywhere public. If you do it can and will be compromised.
-5. Save your **Bot Token** somewhere safe to use in the project settings later.
-6. In the `General Information` tab, grab the **Application ID**.
-7. Replace `<APPLICATION_ID_HERE>` in the following URL and visit it in the browser to invite your bot to your new test server.
-```plaintext
-https://discordapp.com/api/oauth2/authorize?client_id=<APPLICATION_ID_HERE>&permissions=8&scope=bot
-```
-Optionally, you can generate your own invite url in the `OAuth` tab, after selecting `bot` as the scope.
+1. Go to the [Discord Developers Portal](https://discord.com/developers/applications).
+1. Click on the `New Application` button, enter your desired bot name, and click `Create`.
+1. In the `Installation` tab, set `Install Link` to `None` and click `Save Changes`.
+1. In the `Bot` tab:
+    - Turn off the `Public Bot` setting.
+    - Turn on the `Message Content Intent` setting.
+    - If setting up Python Bot, also turn on the `Server Members Intent` setting.
+    - ...and click `Save Changes`.
+1. Click the `Reset Token` button and then `Copy` the generated token. Save it somewhere safe, as you will need it later.
+    > **Note:** **DO NOT** post this token anywhere public, as it grants complete control of your bot.
+1. In the  `OAuth2` tab, select the `bot` scope and `Administrator` permission, and visit the generated URL in your Discord app or browser to invite the bot to your server.

pydis_site/apps/content/resources/guides/pydis-guides/contributing/docker.md

@@ -5,7 +5,7 @@ icon: fab fa-docker
 toc: 2
 ---
 
-Both our [Site](../site/) and [Bot](../bot/) projects use Docker and Docker-Compose during development in order to provide an easy to setup and consistent development environment.
+Both our [Site](../site/) and [Bot](../bot/) projects use Docker and Docker Compose during development in order to provide an easy to setup and consistent development environment.
 
 Consider reading some of the following topics if you're interested in learning more about Docker itself:
 
@@ -15,12 +15,12 @@ Consider reading some of the following topics if you're interested in learning m
 
 # Docker Installation
 You can find installation guides available for your respective OS from the official Docker documentation:
-[https://docs.docker.com/install/](https://docs.docker.com/install/)
+[https://docs.docker.com/get-started/get-docker/](https://docs.docker.com/get-started/get-docker/)
 
 ## After Installing on Linux
 If you're on Linux, there's a few extra things you should do:
 
-1. [**Add your user to the `docker` user group so you don't have to use `sudo` when running docker or docker-compose.**](#add-user-group)
+1. [**Add your user to the `docker` user group so you don't have to use `sudo` when running docker**](#add-user-group)
 2. [**Start up the Docker service.**](#run-the-service)
 3. [**Set the Docker service to start on boot.**](#start-on-boot) **(optional)**
 
@@ -67,7 +67,7 @@ Remove the existing `~/.docker/` directory. It will be automatically re-created
 
 ### Drive has not been shared (Windows users)
 
-When attempting to run the `docker-compose up` command on a Windows machine, you receive the following or similar error message:
+When attempting to run the `docker compose up` command on a Windows machine, you receive the following or similar error message:
 ```text
 ERROR: for bot_bot_1 Cannot create container for service bot: b'Drive has not been shared'
 ```
@@ -85,11 +85,27 @@ Windows has not been configured to share drives with Docker.
 
 3. Click "Apply" and enter appropriate Windows credentials (likely just your own account, if you have administrative privileges).
 
-4. Re-run the `docker-compose up` command.
+4. Re-run the `docker compose up` command.
+
+### Issues running on Apple Silicon
+
+Attempting to run some images on non-amd64 architectures may show an error like this:
+
+```
+no matching manifest for linux/arm64/v8 in the manifest list entries
+```
+
+This is due to some images that we use only being build for amd64.
+
+You can force the use of amd64 by setting the following environment variable before running docker commands:
+
+```
+DOCKER_DEFAULT_PLATFORM=linux/amd64
+```
 
 # Compose Project Names
-When you launch services from a docker-compose, you'll notice the name of the containers aren't just the service name.
-You'll see this when launching your compose, as well as being able to be seen in the command `docker-compose ps` which will list the containers.
+When you launch services using Docker Compose, you'll notice the name of the containers aren't just the service name.
+You'll see this when launching your compose, as well as being able to be seen in the command `docker compose ps` which will list the containers.
 It should match something like this:
 ```
 site_site_1