Merge branch 'main' of https://github.com/python-discord/site into swfarnsworth/smarter-resources/new-resources

9 files changed, 127 insertions, 79 deletions

diff --git a/pydis_site/apps/content/resources/frequently-asked-questions.md b/pydis_site/apps/content/resources/frequently-asked-questions.md
index 8b9945aa..212ea5f8 100644
--- a/pydis_site/apps/content/resources/frequently-asked-questions.md
+++ b/pydis_site/apps/content/resources/frequently-asked-questions.md
@@ -87,6 +87,8 @@ The only file types that we allow on this server are those that Discord supports
 This is because it's easier and safer for people on the server since they do not need to download a file to view it.
 It's also to ease the burden on our moderators, otherwise they would have to download and check the files posted to the server.
 
+Even though Discord does support previewing of files like `.txt` and `.py`, that support is only available on Desktop, not mobile. Additionally, we prefer people to use hastebin as it encourages them to only copy over the relevant code snippets instead of their whole code; this makes helping much easier for all involved.
+
 If you want to share code please use our hosted hastebin, [paste.pythondiscord.com](http://paste.pythondiscord.com).
 
 
diff --git a/pydis_site/apps/content/resources/guides/pydis-guides/contributing/cloning-repository.md b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/cloning-repository.md
index fad54374..23d525b8 100644
--- a/pydis_site/apps/content/resources/guides/pydis-guides/contributing/cloning-repository.md
+++ b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/cloning-repository.md
@@ -6,26 +6,29 @@ icon: fab fa-github
 
 > **Note:** The process varies depending on your choice of code editor / IDE, so refer to one of the following guides:
 
-- [Cloning with PyCharm](#cloning-with-pycharm)
 - [Cloning with the command line](#cloning-with-the-command-line)
+- [Cloning with PyCharm](#cloning-with-pycharm)
 
 The following will use the [Sir-Lancebot](https://github.com/python-discord/sir-lancebot/) repository as an example, but the steps are the same for all other repositories. You should have already retrieved your fork's Git URL as described in [**Creating a Fork**](../forking-repository).
 
 ---
 
-## Cloning with PyCharm
-1. Load up PyCharm and click `Get from VCS`.<br>
-![Create Project in PyCharm](/static/images/content/contributing/pycharm_create_project.png)
-2. Enter the URL of your forked repository.
-3. Change the directory if you desire and click `Clone`.<br>
-![Clone Git Project in Pycharm](/static/images/content/contributing/pycharm_checkout.png)
-
----
-
 ## Cloning with the command line
+
 1. Clone your forked repository using `git clone` followed by your fork's Git URL. Then, change your working directory to the repository.
+
 ```shell
 $ git clone https://github.com/<your username>/sir-lancebot
 ...
 $ cd sir-lancebot
 ```
+
+---
+
+## Cloning with PyCharm
+
+1. Load up PyCharm and click `Get from VCS`.<br>
+   ![Create Project in PyCharm](/static/images/content/contributing/pycharm_create_project.png)
+2. Enter the URL of your forked repository.
+3. Change the directory if you desire and click `Clone`.<br>
+   ![Clone Git Project in Pycharm](/static/images/content/contributing/pycharm_checkout.png)
diff --git a/pydis_site/apps/content/resources/guides/pydis-guides/contributing/contributing-guidelines/supplemental-information.md b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/contributing-guidelines/supplemental-information.md
index 24dc9aa9..70d47563 100644
--- a/pydis_site/apps/content/resources/guides/pydis-guides/contributing/contributing-guidelines/supplemental-information.md
+++ b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/contributing-guidelines/supplemental-information.md
@@ -40,7 +40,7 @@ If the linter complains, the commit is aborted so that you can fix the linting e
 That way, you never commit the problematic code in the first place!
 
 Please refer to the project-specific documentation to see how to setup and run those tools.
-In most cases, you can install pre-commit using `pipenv run precommit` or `poetry run task precommit`, and lint using `pipenv run lint` or `poetry run task lint`.
+In most cases, you can install pre-commit using `poetry run task precommit`, and lint using `poetry run task lint`.
 
 ## Type Hinting
 
diff --git a/pydis_site/apps/content/resources/guides/pydis-guides/contributing/installing-project-dependencies.md b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/installing-project-dependencies.md
index ba5b3d1b..26d6de30 100644
--- a/pydis_site/apps/content/resources/guides/pydis-guides/contributing/installing-project-dependencies.md
+++ b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/installing-project-dependencies.md
@@ -6,40 +6,36 @@ icon: fab fa-python
 
 > **Note:** The process varies depending on your choice of code editor / IDE, so refer to one of the following guides:
 
-- [Installing dependencies with PyCharm](#installing-dependencies-with-pycharm)
 - [Installing dependencies with the command line](#installing-dependencies-with-the-command-line)
+- [Installing dependencies with PyCharm](#installing-dependencies-with-pycharm)
 
 The following will use the [Sir-Lancebot](https://github.com/python-discord/sir-lancebot/) repository as an example, but the steps are the same for all other repositories.
 You should have already cloned your fork as described in [**Cloning a Repository**](../cloning-repository).
 
 ---
 
-## Installing dependencies with PyCharm
-1. Load up your project in PyCharm.
-2. Go to the Project Settings by clicking `File`, then `Settings...`. Alternatively, use the shortcut key: `Ctrl+Alt+S` (`command+comma` on Mac OS).
-3. Install the [poetry plugin](https://plugins.jetbrains.com/plugin/14307-poetry). (**Note:** This is not required for the site)
-4. Navigate to `Project Interpreter`, then click the gear icon and click `Add`.
-![PyCharm Interpreter Settings](/static/images/content/contributing/pycharm_interpreter.png)
-5. If installing dependencies for the site, click `Pipenv Environment`, otherwise, click `Poetry Environment`, then click `OK`.
-![PyCharm Pipenv Environment](/static/images/content/contributing/pycharm_pipenv.png)
-6. PyCharm will automatically install the packages required into a virtual environment.
-![PyCharm Project Interpreter](/static/images/content/contributing/pycharm_pipenv_success.png)
-
----
-
 ## Installing dependencies with the command line
+
 1. Make sure you are in the root project directory. This directory will always have a file titled `README.md`.
 2. Install project and development dependencies. Remember to also set up pre-commit hooks to ensure your pushed commits will never fail linting.
----
 
-- Site:
-```shell
-$ pipenv sync --dev
-$ pipenv run precommit
-```
+---
 
-- Other projects:
 ```shell
 $ poetry install
 $ poetry run task precommit
 ```
+
+---
+
+## Installing dependencies with PyCharm
+
+1. Load up your project in PyCharm.
+2. Go to the Project Settings by clicking `File`, then `Settings...`. Alternatively, use the shortcut key: `Ctrl+Alt+S` (`command+comma` on Mac OS).
+3. Install the [poetry plugin](https://plugins.jetbrains.com/plugin/14307-poetry).
+4. Navigate to `Project Interpreter`, then click the gear icon and click `Add`.<br/>
+   ![PyCharm Interpreter Settings](/static/images/content/contributing/pycharm_interpreter.png)<br/>
+5. Click `Poetry Environment`, then click `OK`.<br/>
+   ![PyCharm Poetry Environment](/static/images/content/contributing/pycharm_poetry.png)<br/>
+6. PyCharm will automatically install the packages required into a virtual environment.<br/>
+   ![PyCharm Project Interpreter](/static/images/content/contributing/pycharm_poetry_success.png)
diff --git a/pydis_site/apps/content/resources/guides/pydis-guides/contributing/site.md b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/site.md
index 75d27d99..24227f24 100644
--- a/pydis_site/apps/content/resources/guides/pydis-guides/contributing/site.md
+++ b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/site.md
@@ -7,9 +7,9 @@ toc: 1
 
 # Requirements
 
-- [Python 3.8](https://www.python.org/downloads/)
-- [Pipenv](https://github.com/pypa/pipenv#installation)
-    - `pip install pipenv`
+- [Python 3.9](https://www.python.org/downloads/)
+- [Poetry](https://python-poetry.org/docs/#installation)
+    - `pip install poetry`
 - [Git](https://git-scm.com/downloads)
     - [Windows](https://git-scm.com/download/win)
     - [MacOS](https://git-scm.com/download/mac) or `brew install git`
@@ -62,6 +62,7 @@ Run the following queries to create the user and database:
 ```sql
 CREATE USER pysite WITH SUPERUSER PASSWORD 'pysite';
 CREATE DATABASE pysite WITH OWNER pysite;
+CREATE DATABASE metricity WITH OWNER pysite;
 ```
 
 Finally, enter `/q` to exit psql.
@@ -78,6 +79,9 @@ SECRET_KEY=suitable-for-development-only
 STATIC_ROOT=staticfiles
 ```
 
+The [Configuration in Detail](#configuration-in-detail) section contains
+detailed information about these settings.
+
 #### Notes regarding `DATABASE_URL`
 
 - If the database is hosted locally i.e. on the same machine as the webserver, then use `localhost` for the host. Windows and macOS users may need to use the [Docker host IP](../hosts-file/#windows) instead.
@@ -122,10 +126,10 @@ If you're not using Docker, then use [pg_ctl](https://www.postgresql.org/docs/cu
 
 ### Webserver
 
-Starting the webserver is done simply through pipenv:
+Starting the webserver is done simply through poetry:
 
 ```shell
-pipenv run start
+poetry run task start
 ```
 
 ---
@@ -142,3 +146,36 @@ Unless you are editing the Dockerfile or docker-compose.yml, you shouldn't need
 Django provides an interface for administration with which you can view and edit the models among other things.
 
 It can be found at [http://admin.pythondiscord.local:8000](http://admin.pythondiscord.local:8000). The default credentials are `admin` for the username and `admin` for the password.
+
+---
+
+# Configuration in detail
+
+The website is configured through the following environment variables:
+
+## Essential
+- **`DATABASE_URL`**: A string specifying the PostgreSQL database to connect to,
+  in the form `postgresql://user:password@host/database`, such as
+  `postgresql://joethedestroyer:ihavemnesia33@localhost/pysite_dev`
+
+- **`METRICITY_DB_URL`**: A string specifying the PostgreSQL metric database to
+ connect to, in the same form as `$DATABASE_URL`.
+
+- **`DEBUG`**: Controls Django's internal debugging setup. Enable this when
+  you're developing locally. Optional, defaults to `False`.
+
+- **`LOG_LEVEL`**: Any valid Python `logging` module log level - one of `DEBUG`,
+  `INFO`, `WARN`, `ERROR` or `CRITICAL`. When using debug mode, this defaults to
+  `INFO`. When testing, defaults to `ERROR`. Otherwise, defaults to `WARN`.
+
+## Deployment
+- **`ALLOWED_HOSTS`**: A comma-separated lists of alternative hosts to allow to
+  host the website on, when `DEBUG` is not set. Optional, defaults to the
+  `pythondiscord.com` family of domains.
+
+- **`SECRET_KEY`**: The secret key used in various parts of Django. Keep this
+  secret as the name suggests! This is managed for you in debug setups.
+
+- **`STATIC_ROOT`**: The root in which `python manage.py collectstatic`
+  collects static files. Optional, defaults to `/app/staticfiles` for the
+  standard Docker deployment.
diff --git a/pydis_site/apps/content/resources/guides/pydis-guides/help-channel-guide.md b/pydis_site/apps/content/resources/guides/pydis-guides/help-channel-guide.md
index 2a6e7781..8b7c5584 100644
--- a/pydis_site/apps/content/resources/guides/pydis-guides/help-channel-guide.md
+++ b/pydis_site/apps/content/resources/guides/pydis-guides/help-channel-guide.md
@@ -32,7 +32,7 @@ If you're not sure where to post, feel free to ask us which channel is relevant
 
 Our general help channels move at a fast pace, and attract a far more diverse spectrum of helpers.
 This is a great choice for a generic Python question, and a good choice if you need an answer as soon as possible.
-It's particularly important to [ask good questions](..guides/asking-good-questions) when asking in these channels, or you risk not getting an answer and having your help channel be claimed by someone else.
+It's particularly important to [ask good questions](../asking-good-questions) when asking in these channels, or you risk not getting an answer and having your help channel be claimed by someone else.
 
 ## How To Claim a Channel
 
diff --git a/pydis_site/apps/content/tests/helpers.py b/pydis_site/apps/content/tests/helpers.py
index 29140375..d897c024 100644
--- a/pydis_site/apps/content/tests/helpers.py
+++ b/pydis_site/apps/content/tests/helpers.py
@@ -1,4 +1,13 @@
-from pyfakefs.fake_filesystem_unittest import TestCase
+from pathlib import Path
+
+from pyfakefs import fake_filesystem_unittest
+
+
+# Set the module constant within Patcher to use the fake filesystem
+# https://jmcgeheeiv.github.io/pyfakefs/master/usage.html#modules-to-reload
+with fake_filesystem_unittest.Patcher() as _:
+    BASE_PATH = Path("res")
+
 
 # Valid markdown content with YAML metadata
 MARKDOWN_WITH_METADATA = """
@@ -41,11 +50,11 @@ PARSED_METADATA = {
 PARSED_CATEGORY_INFO = {"title": "Category Name", "description": "Description"}
 
 
-class MockPagesTestCase(TestCase):
+class MockPagesTestCase(fake_filesystem_unittest.TestCase):
     """
     TestCase with a fake filesystem for testing.
 
-    Structure:
+    Structure (relative to BASE_PATH):
     ├── _info.yml
     ├── root.md
     ├── root_without_metadata.md
@@ -68,24 +77,27 @@ class MockPagesTestCase(TestCase):
         """Create the fake filesystem."""
         self.setUpPyfakefs()
 
-        self.fs.create_file("_info.yml", contents=CATEGORY_INFO)
-        self.fs.create_file("root.md", contents=MARKDOWN_WITH_METADATA)
-        self.fs.create_file("root_without_metadata.md", contents=MARKDOWN_WITHOUT_METADATA)
-        self.fs.create_file("not_a_page.md/_info.yml", contents=CATEGORY_INFO)
-        self.fs.create_file("category/_info.yml", contents=CATEGORY_INFO)
-        self.fs.create_file("category/with_metadata.md", contents=MARKDOWN_WITH_METADATA)
-        self.fs.create_file("category/subcategory/_info.yml", contents=CATEGORY_INFO)
+        self.fs.create_file(f"{BASE_PATH}/_info.yml", contents=CATEGORY_INFO)
+        self.fs.create_file(f"{BASE_PATH}/root.md", contents=MARKDOWN_WITH_METADATA)
+        self.fs.create_file(
+            f"{BASE_PATH}/root_without_metadata.md", contents=MARKDOWN_WITHOUT_METADATA
+        )
+        self.fs.create_file(f"{BASE_PATH}/not_a_page.md/_info.yml", contents=CATEGORY_INFO)
+        self.fs.create_file(f"{BASE_PATH}/category/_info.yml", contents=CATEGORY_INFO)
+        self.fs.create_file(
+            f"{BASE_PATH}/category/with_metadata.md", contents=MARKDOWN_WITH_METADATA
+        )
+        self.fs.create_file(f"{BASE_PATH}/category/subcategory/_info.yml", contents=CATEGORY_INFO)
         self.fs.create_file(
-            "category/subcategory/with_metadata.md", contents=MARKDOWN_WITH_METADATA
+            f"{BASE_PATH}/category/subcategory/with_metadata.md", contents=MARKDOWN_WITH_METADATA
         )
         self.fs.create_file(
-            "category/subcategory/without_metadata.md", contents=MARKDOWN_WITHOUT_METADATA
+            f"{BASE_PATH}/category/subcategory/without_metadata.md",
+            contents=MARKDOWN_WITHOUT_METADATA
         )
 
-        # There is always a `tmp` directory in the filesystem, so make it a category
-        # for testing purposes.
-        # See: https://jmcgeheeiv.github.io/pyfakefs/release/usage.html#os-temporary-directories
-        self.fs.create_file("tmp/_info.yml", contents=CATEGORY_INFO)
-        self.fs.create_file("tmp.md", contents=MARKDOWN_WITH_METADATA)
-        self.fs.create_file("tmp/category/_info.yml", contents=CATEGORY_INFO)
-        self.fs.create_dir("tmp/category/subcategory_without_info")
+        temp = f"{BASE_PATH}/tmp"  # noqa: S108
+        self.fs.create_file(f"{temp}/_info.yml", contents=CATEGORY_INFO)
+        self.fs.create_file(f"{temp}.md", contents=MARKDOWN_WITH_METADATA)
+        self.fs.create_file(f"{temp}/category/_info.yml", contents=CATEGORY_INFO)
+        self.fs.create_dir(f"{temp}/category/subcategory_without_info")
diff --git a/pydis_site/apps/content/tests/test_utils.py b/pydis_site/apps/content/tests/test_utils.py
index 6612e44c..be5ea897 100644
--- a/pydis_site/apps/content/tests/test_utils.py
+++ b/pydis_site/apps/content/tests/test_utils.py
@@ -4,7 +4,7 @@ from django.http import Http404
 
 from pydis_site.apps.content import utils
 from pydis_site.apps.content.tests.helpers import (
-    MockPagesTestCase, PARSED_CATEGORY_INFO, PARSED_HTML, PARSED_METADATA
+    BASE_PATH, MockPagesTestCase, PARSED_CATEGORY_INFO, PARSED_HTML, PARSED_METADATA
 )
 
 
@@ -12,41 +12,46 @@ class GetCategoryTests(MockPagesTestCase):
     """Tests for the get_category function."""
 
     def test_get_valid_category(self):
-        result = utils.get_category(Path("category"))
+        result = utils.get_category(Path(BASE_PATH, "category"))
 
         self.assertEqual(result, {"title": "Category Name", "description": "Description"})
 
     def test_get_nonexistent_category(self):
         with self.assertRaises(Http404):
-            utils.get_category(Path("invalid"))
+            utils.get_category(Path(BASE_PATH, "invalid"))
 
     def test_get_category_with_path_to_file(self):
         # Valid categories are directories, not files
         with self.assertRaises(Http404):
-            utils.get_category(Path("root.md"))
+            utils.get_category(Path(BASE_PATH, "root.md"))
 
     def test_get_category_without_info_yml(self):
         # Categories should provide an _info.yml file
         with self.assertRaises(FileNotFoundError):
-            utils.get_category(Path("tmp/category/subcategory_without_info"))
+            utils.get_category(Path(BASE_PATH, "tmp/category/subcategory_without_info"))
 
 
 class GetCategoriesTests(MockPagesTestCase):
     """Tests for the get_categories function."""
 
     def test_get_root_categories(self):
-        result = utils.get_categories(Path("."))
+        result = utils.get_categories(BASE_PATH)
 
         info = PARSED_CATEGORY_INFO
-        self.assertEqual(result, {"category": info, "tmp": info, "not_a_page.md": info})
+        categories = {
+            "category": info,
+            "tmp": info,
+            "not_a_page.md": info,
+        }
+        self.assertEqual(result, categories)
 
     def test_get_categories_with_subcategories(self):
-        result = utils.get_categories(Path("category"))
+        result = utils.get_categories(Path(BASE_PATH, "category"))
 
         self.assertEqual(result, {"subcategory": PARSED_CATEGORY_INFO})
 
     def test_get_categories_without_subcategories(self):
-        result = utils.get_categories(Path("category/subcategory"))
+        result = utils.get_categories(Path(BASE_PATH, "category/subcategory"))
 
         self.assertEqual(result, {})
 
@@ -56,14 +61,14 @@ class GetCategoryPagesTests(MockPagesTestCase):
 
     def test_get_pages_in_root_category_successfully(self):
         """The method should successfully retrieve page metadata."""
-        root_category_pages = utils.get_category_pages(Path("."))
+        root_category_pages = utils.get_category_pages(BASE_PATH)
         self.assertEqual(
             root_category_pages, {"root": PARSED_METADATA, "root_without_metadata": {}}
         )
 
     def test_get_pages_in_subcategories_successfully(self):
         """The method should successfully retrieve page metadata."""
-        category_pages = utils.get_category_pages(Path("category"))
+        category_pages = utils.get_category_pages(Path(BASE_PATH, "category"))
 
         # Page metadata is properly retrieved
         self.assertEqual(category_pages, {"with_metadata": PARSED_METADATA})
@@ -84,10 +89,10 @@ class GetPageTests(MockPagesTestCase):
 
         for msg, page_path, expected_html, expected_metadata in cases:
             with self.subTest(msg=msg):
-                html, metadata = utils.get_page(Path(page_path))
+                html, metadata = utils.get_page(Path(BASE_PATH, page_path))
                 self.assertEqual(html, expected_html)
                 self.assertEqual(metadata, expected_metadata)
 
     def test_get_nonexistent_page_returns_404(self):
         with self.assertRaises(Http404):
-            utils.get_page(Path("invalid"))
+            utils.get_page(Path(BASE_PATH, "invalid"))
diff --git a/pydis_site/apps/content/tests/test_views.py b/pydis_site/apps/content/tests/test_views.py
index 74d38f78..b6e752d6 100644
--- a/pydis_site/apps/content/tests/test_views.py
+++ b/pydis_site/apps/content/tests/test_views.py
@@ -3,27 +3,20 @@ from unittest import TestCase
 
 from django.http import Http404
 from django.test import RequestFactory, SimpleTestCase, override_settings
-from pyfakefs import fake_filesystem_unittest
 
 from pydis_site.apps.content.tests.helpers import (
-    MockPagesTestCase, PARSED_CATEGORY_INFO, PARSED_HTML, PARSED_METADATA
+    BASE_PATH, MockPagesTestCase, PARSED_CATEGORY_INFO, PARSED_HTML, PARSED_METADATA
 )
 from pydis_site.apps.content.views import PageOrCategoryView
 
 
-# Set the module constant within Patcher to use the fake filesystem
-# https://jmcgeheeiv.github.io/pyfakefs/master/usage.html#modules-to-reload
-with fake_filesystem_unittest.Patcher() as _:
-    BASE_PATH = Path(".")
-
-
 def patch_dispatch_attributes(view: PageOrCategoryView, location: str) -> None:
     """
     Set the attributes set in the `dispatch` method manually.
 
     This is necessary because it is never automatically called during tests.
     """
-    view.location = Path(location)
+    view.location = Path(BASE_PATH, location)
 
     # URL location on the filesystem
     view.full_location = view.location