finished detailed, screenshot full, putting python on path guide

16 files changed, 152 insertions, 12 deletions

diff --git a/pydis_site/apps/content/resources/guides/python-guides/windows/common-issues.md b/pydis_site/apps/content/resources/guides/python-guides/windows/common-issues.md
index 9a09319a..45fd4331 100644
--- a/pydis_site/apps/content/resources/guides/python-guides/windows/common-issues.md
+++ b/pydis_site/apps/content/resources/guides/python-guides/windows/common-issues.md
@@ -1,6 +1,7 @@
 ---
 title: Common issues using Python on Windows
 description: A list of common issues with Python on Windows and how to fix them
+icon: fab fa-windows
 ---
 
 TODO!!! rewrite/rearrange in list form with lots of links to other resources
diff --git a/pydis_site/apps/content/resources/guides/python-guides/windows/installing-python.md b/pydis_site/apps/content/resources/guides/python-guides/windows/installing-python.md
index 09c82865..e9cf6343 100644
--- a/pydis_site/apps/content/resources/guides/python-guides/windows/installing-python.md
+++ b/pydis_site/apps/content/resources/guides/python-guides/windows/installing-python.md
@@ -1,6 +1,7 @@
 ---
 title: Installing Python on Windows
 description: How we recommend installing Python on Windows
+icon: fab fa-windows
 ---
 
 The recommended way to install Python on windows is directly from the
diff --git a/pydis_site/apps/content/resources/guides/python-guides/windows/microsoft-store.md b/pydis_site/apps/content/resources/guides/python-guides/windows/microsoft-store.md
index 6ddf1a00..e4bac067 100644
--- a/pydis_site/apps/content/resources/guides/python-guides/windows/microsoft-store.md
+++ b/pydis_site/apps/content/resources/guides/python-guides/windows/microsoft-store.md
@@ -1,6 +1,7 @@
 ---
 title: Why not to install Python from the Microsoft Store
 description: The drawbacks of installing the Microsoft Store versions of Python
+icon: fab fa-windows
 ---
 
 [<img style="margin:1rem;" align="right" width="480px"
diff --git a/pydis_site/apps/content/resources/guides/python-guides/windows/putting-python-on-path.md b/pydis_site/apps/content/resources/guides/python-guides/windows/putting-python-on-path.md
index 0627516b..b78fc5d4 100644
--- a/pydis_site/apps/content/resources/guides/python-guides/windows/putting-python-on-path.md
+++ b/pydis_site/apps/content/resources/guides/python-guides/windows/putting-python-on-path.md
@@ -1,8 +1,12 @@
 ---
 title: Putting Python on Path
 description: How to make sure Python is properly on the Windows Path environment variable
+icon: fab fa-windows
+toc: 2
 ---
 
+<!-- TODO Test the guide if you have no admin privileges and mention the differences. -->
+
 If you're on Windows and know you have [Python installed from python.org](https://www.python.org/downloads/) ([our
 recommended way](../installing-python.md)) but you're still getting errors like
 
@@ -17,7 +21,7 @@ environment variable is improperly configured for Python. This just means Window
 installation.
 
 The Path (or PATH) environment variable is what Windows uses to locate executables needed on the command line. Whenever
-you type a command name in your terminal, like `python` or `pip`, the terminal looks for an exe with the same name in
+you type a command name in your terminal, like `python` or `pip`, the terminal looks for a program of the same name in
 the folders listed in the Path, so the command can be run.
 
 The [Python installer](https://www.python.org/downloads/) provides an option to add Python to your Path automatically,
@@ -34,7 +38,8 @@ method](#advanced-method-manually-edit-the-path) that explains how to edit the P
 
 The easiest and safest way to add Python to Path is by rerunning the installer. For this you will need the same
 installer you used to install Python, which you can download again if needed from
-[python.org](https://www.python.org/downloads/windows/), or it may still be in your Downloads folder (it's a file like `python-3.11.0-amd64.exe`).
+[python.org](https://www.python.org/downloads/windows/), or it may still be in your Downloads folder (it's a file like
+`python-3.11.0-amd64.exe`).
 
 Once you have it, here are the steps to modify the installation to add Python to Path:
 
@@ -58,11 +63,18 @@ Once you have it, here are the steps to modify the installation to add Python to
 
     ![Step 5](/static/images/content/python-on-windows/safe_path_method_5.png)
 
-Then, after a moment, it should say "Modify was successful" and you can close the installer, and Python should now be on your Path! **You will need to restart any terminals or editors you have open before they detect the change.**
+Then, after a moment, it should say "Modify was successful" and you can close the installer, and Python should now be on
+your Path! **You will need to restart any terminals or editors you have open before they detect the change.**
+
+(These steps are for the Python 3.11 installer may differ slightly for other versions. Also, for step 1, if preferred,
+you can find your Python installation in the "Apps & features" Windows settings and hit "Modify" there, but you will
+still need to locate the installer exe at step 5 if it's not already in Downloads.)
 
-(These steps are for the Python 3.11 installer may differ slightly for other versions. Also, for step 1, if preferred, you can find your Python installation in the "Apps & features" Windows settings and hit "Modify" there, but you will still need to locate the installer exe at step 5 if it's not already in Downloads.)
+### Verifying your changes
 
-To check that it worked, open a terminal &mdash; Command Prompt, Powershell, an IDE-integrated terminal, [Windows Terminal](https://apps.microsoft.com/store/detail/windows-terminal/9N0DX20HK701), whichever you prefer, just _not_ the Python terminal with the `>>>` prompt &mdash; and run
+To check that it worked, open a fresh terminal &mdash; Command Prompt, Powershell, an IDE-integrated terminal, [Windows
+Terminal](https://apps.microsoft.com/store/detail/windows-terminal/9N0DX20HK701), whichever you prefer, just _not_ the
+Python terminal with the `>>>` prompt &mdash; and run
 
 ```text
 python -V
@@ -88,19 +100,142 @@ to see that the exact executable that is currently running Python is what you ex
 
 ![Checking Python executable.](/static/images/content/python-on-windows/testing_path_worked_2.png)
 
-(Type `exit()` from here to go back to the normal terminal.)
+Type `exit()` from here to go back to the normal terminal.
 
 <!-- TODO mention that py may open a different version and link to py launcher guide. -->
 
-Of course your username will probably not be "r" like mine is, and your executable path may differ from
+Of course your username will probably not be "r", and your executable path may differ from
 `C:\Users\<user>\AppData\Local\Programs\Python\Python311` depending on where you chose to install Python and what
 version you have. The last folder will be `Python310` for Python 3.10, `Python39` for Python 3.9, etc. But those
-differences don't matter if `python` and `pip` and other things like `pyinstaller` (if you've pip installed it) now work
-for you!
+differences don't matter if `python` and `pip` and other things like `pyinstaller` (if you've [pip
+installed](https://pypi.org/project/pyinstaller/) it) now work for you!
 
-Hopefully things are indeed working, _however_, it is possible that, due to having multiple Python versions, or other mixups,
-the commands are still not behaving how you expect. If so, read on to learn how to manually edit the Path environment variable. It's really not that hard and a super useful Windows skill to know for more than just Python.
+Hopefully things are indeed working, however, it is possible that, due to having multiple Python versions, or other
+mixups, the commands are still not behaving how you expect. If so, read on to learn how to manually edit the Path. (If
+you already did that, open a help channel on the [Python Discord server](https://discord.com/invite/python) and someone
+will hopefully be able to help.)
 
 ## Advanced Method: Manually edit the Path
 
-TODO!!!
+As mentioned above, the Path (often called "PATH", though it shows up as "Path") is what Windows uses to locate
+executables needed on the command line. If it's misconfigured, `python` and `pip` commands may not work as
+expected.
+
+"Path" is the name of a Windows environment variable whose value is simply a list of paths to folders on the system. A
+_path_ is just string that locates a folder, like `C:\Program Files\Git\cmd`. An _environment variable_ is a variable (a
+thing with a name and a value) that is available to the entire system, or at least to an entire user of the system.
+
+In fact, the Windows Path is technically _two_ environment variables, two lists of folders: a System one and a User one.
+But, as explained [here](https://superuser.com/a/878382), when actually used, the User Path is appended to the System
+Path, forming one long list.
+
+So, how it works is whenever you type a command like `python` into a terminal, the terminal looks for a matching
+runnable file like `python.exe` (or [`python.bat`](https://en.wikipedia.org/wiki/Batch_file)) in each of the folders
+listed in the Path, starting with the System Path (top to bottom), and then the User Path (top to bottom). It stops
+searching on the first one it finds and runs that program with the command line arguments you may have given it, hence
+(hopefully) running Python from an installed `python.exe`.
+
+If it can't find a runnable file that matches the command name, it spits out an error like:
+
+```text
+foobar: The term 'foobar' is not recognized as the name of a cmdlet, function, script file, or operable program.
+```
+
+Or, in the case of not finding `python`, it may [open up the Microsoft
+store](../microsoft-store.md#confusing-app-execution-alias-behaviour).
+
+Again, the Path lookup order is:
+
+> System Path (top to bottom) &rarr; User Path (top to bottom) &rarr; Command not found error
+
+### Adding Python to your Path
+
+Here the common case of adding Python to the Windows Path is detailed. Though knowing how to manually modify the Path is
+handy beyond that whenever you need to change or debug which programs run on the command line. (The less customizable
+but [safer method is above](#safe-method-let-the-installer-add-python-to-path) if you missed it.)
+
+Follow these steps to add Python to the Path:
+
+1.  First, find folder path your Python executable is in. There are a couple ways to do this:
+
+    **Way 1**: Run `py -0p` on the command line and copy the folder path of the version you want:
+
+    ![Finding exe with py.](/static/images/content/python-on-windows/finding_exe_1.png)
+
+    **Way 2**: Run `import sys; print(sys.executable)` in Python on your PC and copy the folder path it prints out:
+
+    ![Finding exe in repl.](/static/images/content/python-on-windows/finding_exe_2.png)
+
+    Either way I end up with `C:\Users\r\AppData\Local\Programs\Python\Python311\` (no `python.exe` at the end).
+    Your path will of course be based on your username (my username is "r") and your version of Python, such as
+    `C:\Users\ducky\AppData\Local\Programs\Python\Python39\` if your username is "ducky" and you're using Python 3.9.
+    Copy your path, we'll use it in steps 6 and 7.
+
+2.  [This step is optional but helpful to see what's going on.] Copy the folder path from step 1 into the path bar of
+    Windows File Explorer. In the folder you should be able to see `python.exe`, and in the Scripts subfolder, things
+    like `pip.exe` and `pyinstaller.exe` (if you have it installed).
+
+    ![Finding exes in folder.](/static/images/content/python-on-windows/finding_exe_3.png)
+
+    These are the executables we want the command line to be able to find via the Windows Path.
+
+3.  Now, type "environment variables" in the Start menu or Start search box and open the "Edit the system environment
+    variables" option.
+
+    ![Step 3](/static/images/content/python-on-windows/edit_path_1.png)
+
+4.  Hit the "Environment Variables..." button.
+
+    ![Step 4](/static/images/content/python-on-windows/edit_path_2.png)
+
+5.  In a new window you should see two "Path" variables, one under "User variables for &lt;user&gt;" and one under
+    "System variables". Select one of them (most likely the User Path) and hit the "Edit..." button underneath it.
+
+    I suggest using the User Path (what the screenshots show) for the default installation of Python. In general, only
+    put things on the System Path if they are installed for all users (e.g. in `C:\Program Files` or `C:\`) and you're
+    certain they won't overshadow anything in User Paths. **Remember, the System Path takes precedence over the User
+    Path when commands are looked up.**
+
+    ![Step 5](/static/images/content/python-on-windows/edit_path_3.png)
+
+    (Don't worry if your variables or Path contents differ a bit from those shown.)
+
+6.  The third window that opens is where the Path is actually edited. It shows the ordered list of the folders on the
+    Path and you can select the entries, edit them, reorder them, make new ones, delete them and so on. (Don't delete
+    any unless you know what you're doing!)
+
+    We want to add the Python executable path we found in step 1 as a new entry, so click "New" and paste in the path.
+
+    ![Step 6](/static/images/content/python-on-windows/edit_path_4.png)
+
+7.  We also need to add the Python Scripts directory to the Path to have commands like `pip` and `pyinstaller` work. So
+    hit "New" and paste in the Python executable path again, and type "Scripts" after it.
+
+    ![Step 7](/static/images/content/python-on-windows/edit_path_5.png)
+
+8.  Finally, select each of the paths you just added in turn and move them to the very top of the list using the "Move
+    Up" button. (Their relative order should not matter.)
+
+    ![Step 8](/static/images/content/python-on-windows/edit_path_6.png)
+
+    This step may not be strictly necessary, but remember that command lookup happens in order from top to bottom.
+    Python is often bundled with other software that may end up on the Path, so there's there could be another
+    `python.exe` in one of of the other folders on the path that gets in the way. (This exact thing has happened to me when
+    I put `C:\Program Files\Inkscape\bin` on my Path, as [Inkscape](https://inkscape.org/) comes with a copy of Python.)
+
+    Also, the System Path comes first in command lookup, so to be certain you to may want to go back and check the
+    System Path (see step 5) and _carefully_ delete any entry that is a Python executable path blocking the one you just
+    added. Though please, don't delete any Path entries you're aren't sure about! Just in case, for reference, [here are
+    the important looking System Path entries](/static/images/content/python-on-windows/system_path_important.png) on my
+    Windows 10 64-bit PC.
+
+9.  Finish by making sure to hit "OK" on each of the thee "Edit environment variable", "Environment Variable", and
+    "System Properties" windows, and then you're done!
+
+    Python and Python Scripts should not be on your Path! **You will need to restart any terminals or editors you have open before they detect the change.**
+
+At this point you can [verify your changes in the same way as detailed above](#verifying-your-changes). Hopefully it
+works!
+
+(These steps were written with Windows 10 and Python 3.11 in mind, but they should be identical or similar for Windows
+11 and other recent versions of Python.)
diff --git a/pydis_site/apps/content/resources/guides/python-guides/windows/py-launcher.md b/pydis_site/apps/content/resources/guides/python-guides/windows/py-launcher.md
index 673a1759..388177ec 100644
--- a/pydis_site/apps/content/resources/guides/python-guides/windows/py-launcher.md
+++ b/pydis_site/apps/content/resources/guides/python-guides/windows/py-launcher.md
@@ -1,6 +1,7 @@
 ---
 title: The py Launcher on Windows
 description: Common commands and usage of the Windows "py" Python launcher
+icon: fab fa-windows
 ---
 
 When you install Python on Windows fron
diff --git a/pydis_site/apps/content/resources/guides/python-guides/windows/unix-env-on-windows.md b/pydis_site/apps/content/resources/guides/python-guides/windows/unix-env-on-windows.md
index 28322f7c..f52ddfed 100644
--- a/pydis_site/apps/content/resources/guides/python-guides/windows/unix-env-on-windows.md
+++ b/pydis_site/apps/content/resources/guides/python-guides/windows/unix-env-on-windows.md
@@ -1,6 +1,7 @@
 ---
 title: Setting up a Unix-style Python Environment on Windows
 description: How to setup a Unix-style Python environment ready to start coding in
+icon: fab fa-windows
 ---
 
 <!-- TODO? Mention WSL2? -->
diff --git a/pydis_site/static/images/content/python-on-windows/edit_path_1.png b/pydis_site/static/images/content/python-on-windows/edit_path_1.png
new file mode 100644
index 00000000..bf5d4a66
--- /dev/null
+++ b/pydis_site/static/images/content/python-on-windows/edit_path_1.png
diff --git a/pydis_site/static/images/content/python-on-windows/edit_path_2.png b/pydis_site/static/images/content/python-on-windows/edit_path_2.png
new file mode 100644
index 00000000..99c6eae5
--- /dev/null
+++ b/pydis_site/static/images/content/python-on-windows/edit_path_2.png
diff --git a/pydis_site/static/images/content/python-on-windows/edit_path_3.png b/pydis_site/static/images/content/python-on-windows/edit_path_3.png
new file mode 100644
index 00000000..dbc74a97
--- /dev/null
+++ b/pydis_site/static/images/content/python-on-windows/edit_path_3.png
diff --git a/pydis_site/static/images/content/python-on-windows/edit_path_4.png b/pydis_site/static/images/content/python-on-windows/edit_path_4.png
new file mode 100644
index 00000000..bae5631d
--- /dev/null
+++ b/pydis_site/static/images/content/python-on-windows/edit_path_4.png
diff --git a/pydis_site/static/images/content/python-on-windows/edit_path_5.png b/pydis_site/static/images/content/python-on-windows/edit_path_5.png
new file mode 100644
index 00000000..c0338888
--- /dev/null
+++ b/pydis_site/static/images/content/python-on-windows/edit_path_5.png
diff --git a/pydis_site/static/images/content/python-on-windows/edit_path_6.png b/pydis_site/static/images/content/python-on-windows/edit_path_6.png
new file mode 100644
index 00000000..e01d15bc
--- /dev/null
+++ b/pydis_site/static/images/content/python-on-windows/edit_path_6.png
diff --git a/pydis_site/static/images/content/python-on-windows/finding_exe_1.png b/pydis_site/static/images/content/python-on-windows/finding_exe_1.png
new file mode 100644
index 00000000..6b46bef1
--- /dev/null
+++ b/pydis_site/static/images/content/python-on-windows/finding_exe_1.png
diff --git a/pydis_site/static/images/content/python-on-windows/finding_exe_2.png b/pydis_site/static/images/content/python-on-windows/finding_exe_2.png
new file mode 100644
index 00000000..5c6020ec
--- /dev/null
+++ b/pydis_site/static/images/content/python-on-windows/finding_exe_2.png
diff --git a/pydis_site/static/images/content/python-on-windows/finding_exe_3.png b/pydis_site/static/images/content/python-on-windows/finding_exe_3.png
new file mode 100644
index 00000000..753d17e8
--- /dev/null
+++ b/pydis_site/static/images/content/python-on-windows/finding_exe_3.png
diff --git a/pydis_site/static/images/content/python-on-windows/system_path_important.png b/pydis_site/static/images/content/python-on-windows/system_path_important.png
new file mode 100644
index 00000000..1236cf41
--- /dev/null
+++ b/pydis_site/static/images/content/python-on-windows/system_path_important.png