Proofread, tweaked, added links to common windows issues guide. (Also normalized to 120 wide with rewrap vsc ext)

1 files changed, 119 insertions, 146 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 45fd4331..4d8530d5 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
@@ -4,186 +4,159 @@ 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
-
 ### When I run `python` in the terminal I get no result, or the Windows Store opens!
 
-By default Windows has an alias for `python` in the terminal to guide you to
-install it from the Microsoft Store. I would not recommend that you install
-Python from the Microsoft Store, see why [here](../microsoft-store.md).
-To disable this alias, search "App execution aliases" in windows search and
-click on "Manage app execution aliases". In the list you should see two options
-with title "App Installer" and descriptions `python.exe` and `python3.exe`.
-Disable both of them.
+By default Windows has an alias for `python` in the terminal to guide you to install it from the [Microsoft
+Store](https://apps.microsoft.com/store/search/python). We don't recommend installing Python from the Microsoft
+Store, see why [here](../microsoft-store). To disable this alias, search "App execution aliases" in Windows search
+and click on "Manage app execution aliases". In the list you should see two options with title "App Installer" and
+descriptions `python.exe` and `python3.exe`. Disable both of them.
 
-Note that if you are following instructions telling you to run a command
-starting with `python3`, those instructions are intended for Unix/macOS systems.
-Try just using `python` instead.
+Note that if you are following instructions telling you to run a command starting with `python3`, those instructions are
+intended for Unix/macOS systems. Try just using `python` instead.
 
-If after doing this you have an issue with the Python command not being
-detected, see the below question.
+If after doing this you have an issue with the Python command not being detected, see the question below.
 
-### When I try and run my code with `python` in the terminal I get an error saying the command was not recognised
+### When I try and run my code with `python` in the terminal I get an error saying the command was not recognized
 
-If you have not installed Python, you will need to do that. Follow our guide [here](../install-on-windows.md).
+If you have not installed Python, you will need to do that. Follow our guide [here](../installing-python).
 
-If you have installed python and are still having the issue, it is likely that
-you forgot to add to PATH when doing so. See [our guide on adding Python to
-PATH](../python-on-windows.md#changing-path) for how to fix this.
-You can also use the `py` launcher instead of `python` by just replacing
-`python` in your command with `py`. See
-[this guide](../python-on-windows.md#the-py-launcher) for more information
-on that.
+If you have installed python and are still having the issue, it is likely that you didn't check the "Add python.exe to
+PATH" checkbox on the first page of the installer. See [our guide on adding Python to
+PATH](../putting-python-on-path) for how to fix this. You can also use the `py` launcher instead of `python` by just
+replacing `python` in your command with `py`. See [this guide](../py-launcher) for more information on that.
 
 ### I `pip` installed a package but when running my code get a `ModuleNotFoundError`
 
 -   #### Are you actually getting a `ModuleNotFoundError`?
 
-    If you are using a code editor such as VSCode or Pycharm you may get a
-    squiggly line under your import saying the module couldn't be found, it is
-    possible that this is just an mistake by the editor, so try actually running
-    your code with to ensure if it actually errors.
+    If you are using a code editor such as VSCode or PyCharm you may get a squiggly line under your import saying the
+    module couldn't be found, it is possible that this is just an mistake by the editor, so try actually running your
+    code with to ensure if it actually errors.
 
-    If your code runs fine, you could try restarting your editor. If you have
-    newly installed a module it may just not have detected it yet. If that
-    doesn't help, you may need to configure your editor to ensure it is looking
-    for the module in the correct Python environment. See
-    [our guide on virtual environments](./python-on-windows.md#virtual-environments)
-    for more information.
+    If your code runs fine, you could try restarting your editor. If you have newly installed a module it may just not
+    have detected it yet. If that doesn't help, you may need to configure your editor to ensure it is looking for the
+    module in the correct Python environment. See [our guide on virtual environments](dg:TODO) for more information.
 
 -   #### Was the install successful?
 
-    Look out for errors when installing the module you want. If you get an
-    error, that's probably why the import isn't working, so you should look
-    into it. Often a google search will help with this.
+    Look out for errors when installing the module you want. If you get an error, that's probably why the import isn't
+    working, so you should look into it. Often a Google search of the relevant error text will help.
 
 -   #### Did you use the correct module name?
 
-    Double check that you haven't made a typo in the name you are importing, or
-    in what you installed from PyPI, you need to make sure you type the name
-    exactly as it should be.
-
-    Also, **the name you should `import` may not be the same as the name you `pip install`**. Check the module's documentation or PyPI page if you are unsure.
-    Examples of this are:
-
-    -   [**opencv-python**](https://pypi.org/project/opencv-python/): You need to
-        `pip install opencv-python`, but the import has to be `import cv2`
-    -   [**discord.py**](https://pypi.org/project/discord.py/): You need to `pip install discord.py`, but the import has to be `import discord`
-    -   [**python-dotenv**](https://pypi.org/project/python-dotenv/): You need to
-        `pip install python-dotenv`, but the import has to be `import dotenv`
-
--   #### Are you installing to the same environment you're running your code from?
-
-    This is a very common issue. When you install a module from PyPI, you will
-    install it into a single Python environment, the one that the `pip` you
-    invoked is part of. This could be different to the one you are running
-    the script from if it's using a different Python installation,
-    or a virtual environment.
-
-    ###### I'm using Pycharm
-
-    PyCharm creates a virtual environment for each project by default, so if
-    you're installing a module using Pycharm you need to make sure you also run
-    your code through PyCharm. This also applies the other way round, if you
-    want to use a module in PyCharm you need to install it through PyCharm.
-
-    It's also possible to change PyCharm to use your system environment, see
-    [their guide on configuring your interpreter](https://www.jetbrains.com/help/pycharm/configuring-python-interpreter.html)
-    for more information.
-
-    ###### I installed the module using pip from the command line
+    Double check that you haven't made a typo in the name you are importing, or in what you installed from
+    [PyPI](https://pypi.org/), you need to make sure you type the name exactly as it should be.
 
-          Run `pip -V` and look at the path returned it should be in the form
-          `<PATH_TO_PYTHON>\Lib\site-packages\pip`.
+    Also, **the name you should `import` may not be the same as the name you `pip install`**. Check the module's
+    documentation or PyPI page if you are unsure. Examples of this are:
 
-          Then put `import sys;print(sys.executable);sys.exit(0)` at the top
-          (above imports!) of your python file, and run it. The result should be
-          in the form `<PATH_TO_PYTHON>\python.exe`.
+    -   [**opencv-python**](https://pypi.org/project/opencv-python/): You need to `pip install opencv-python`, but the
+        import has to be `import cv2`
+    -   [**discord.py**](https://pypi.org/project/discord.py/): You need to `pip install discord.py`, but the import has
+        to be `import discord`
+    -   [**python-dotenv**](https://pypi.org/project/python-dotenv/): You need to `pip install python-dotenv`, but the
+        import has to be `import dotenv`
+    -   [**Pillow**](https://pypi.org/project/Pillow/): You need to `pip install Pillow`, but the import is
+        usually `from PIL import Image`.
 
-          Now compare that `PATH_TO_PYTHON` to the one from `pip -V`. If they're
-          different, this is the cause of the `ModuleNotFoundError`. Follow the
-          relevant "I'm running my code with ..." section below for how to fix
-          this.
+    Normal imports in Python can't have dashes (`-`) in them as it would be interpreted as subtraction. Though [there
+    are workarounds](https://stackoverflow.com/questions/7583652/python-module-with-a-dash-or-hyphen-in-its-name).
 
-    ###### I'm running my code with `python` from the terminal.
-
-          If you are using a virtual environment, ensure you have activated it before
-          running `pip install`. You can test this by running `pip -V` and checking
-          the path is the one of your virtual environment.
-
-          Alternatively, you can use the `py` command to specify the python version
-          you want to pip install into, e.g. `py -3.9 -m pip install numpy`, and to
-          specify the executable you want to run your code with, e.g. `py -3.9
-          my_script.py`.
-
-          If your `pip` and `python` commands are referring to different python
-          environments at the same time, it's possible your PATH is configured
-          incorrectly. See our
-          [guide for adding Python to PATH](../python-on-windows.md#adding-python-to-your-path)
-          for how to fix this.
-
-    ###### I'm running my code with the button in VSCode
-
-          To run your code from the same environment you installed Python to, set
-          the interpreter to the one at the path you found when running `pip -V`
-          by following
-          [this guide](https://code.visualstudio.com/docs/python/environments#_select-and-activate-an-environment).
-          The path should be in the form `PATH_TO_PYTHON\python.exe`
-
-          Alternatively, you can pip install to the currently activated
-          environment. If you have configured VSCode to use a virtual environment,
-          it should automatically activate it when you open a new terminal, so
-          running the `pip install` command in the VSCode terminal should work. If
-          you are not using a virtual environment, you can use the `py` launcher
-          to specify the installation you want to install to.
-
-### I `pip` installed a command line program but it isn't recognised
-
-You pip installed a command line program like `PyInstaller` or `black` that is
-intended to be run from the command line, but it does not work. Two common causes
-for this are:
-
--   You are using Python from the Microsoft Store
+-   #### Are you installing to the same environment you're running your code from?
 
-    To check if this is the case, type `pip -V`. If the path output includes
-    something like
-    `PythonSoftwareFoundation.Python.3.10_3.10.2288.0_x64__qbz5n2kfra8p0`, you
-    are using Python from the Microsoft Store. To fix this you will either have
-    to use the full path to the scripts you want to use, or uninstall the
-    Microsoft Store Python and install Python properly with the online
-    installer.
+    This is a very common issue. When you install a module from PyPI, you will install it into a single Python
+    environment, the one that the `pip` you invoked is part of. This could be different to the one you are running the
+    script from if it's using a different Python installation, or a virtual environment.
+
+    ##### I'm using PyCharm
+
+    > PyCharm creates a virtual environment for each project by default, so if you're installing a module using Pycharm
+    > you need to make sure you also run your code through PyCharm. This also applies the other way round, if you want
+    > to use a module in PyCharm you need to install it through PyCharm.
+    >
+    > It's also possible to change PyCharm to use your system environment, see [their guide on configuring your
+    > interpreter](https://www.jetbrains.com/help/pycharm/configuring-python-interpreter.html) for more information.
+
+    ##### I installed the module using pip from the command line
+
+    > Run `pip -V` and look at the path returned it should be in the form `<PATH_TO_PYTHON>\Lib\site-packages\pip`.
+    >
+    > Then put `import sys;print(sys.executable);sys.exit(0);` at the top (above imports!) of your python file, and run
+    > it. The result should be in the form `<PATH_TO_PYTHON>\python.exe`.
+    >
+    > Now compare that `PATH_TO_PYTHON` to the one from `pip -V`. If they're different, this is the cause of the
+    > `ModuleNotFoundError`. Follow the relevant "I'm running my code with ..." section below for how to fix this.
+
+    ##### I'm running my code with `python` from the terminal.
+
+    > If you are using a virtual environment, ensure you have activated it before running `pip install`. You can test
+    > this by running `pip -V` and checking the path is the one of your virtual environment.
+    >
+    > Alternatively, you can use the `py` command to specify the python version you want to pip install into, e.g.
+    > `py -3.9 -m pip install numpy`, and to specify the executable you want to run your code with, e.g.
+    > `py -3.9 my_script.py`.
+    >
+    > If your `pip` and `python` commands are referring to different python environments at the same time, it's possible
+    > your PATH is configured incorrectly. See our [guide for adding Python to PATH](../putting-python-on-path) for
+    > how to fix this.
+
+    ##### I'm running my code with the button in VSCode
+
+    > To run your code from the same environment you installed Python to, set the VSCode Python interpreter to the one
+    > at the path you found when running `pip -V` by following [this
+    > guide](https://code.visualstudio.com/docs/python/environments#_select-and-activate-an-environment) (basically
+    > `Ctrl+Shift+P -> Python: Select Interpreter -> select the one desired`). The path should be in the form
+    > `PATH_TO_PYTHON\python.exe`
+    >
+    > Alternatively, you can pip install to the currently activated environment. If you have configured VSCode to use a
+    > virtual environment, it should automatically activate it when you open a new terminal, so running the
+    > `pip install` command in the VSCode terminal should work. If you are not using a virtual environment, you can use
+    > the `py` launcher to specify the installation you want to install to.
+
+### I `pip` installed a command line program but it isn't recognized
+
+You pip installed a command line program like [`pyinstaller`](https://pypi.org/project/pyinstaller/) or
+[`black`](https://pypi.org/project/black/) that is intended to be run from the command line, but it does not work. Two
+common causes for this are:
+
+-   You are using Python from the Microsoft Store ([which we don't recommend](../miscrosoft-store)).
+
+    To check if this is the case, type `pip -V`. If the path output includes something like
+    `PythonSoftwareFoundation.Python.3.10_3.10.2288.0_x64__qbz5n2kfra8p0`, you are using Python from the Microsoft
+    Store. To fix this you will either have to use the full path to the scripts you want to use, or [uninstall the
+    Microsoft Store Python](/static/images/content/python-on-windows/ms_store_uninstall.png) and [install Python
+    properly](../installing-python) with a [python.org installer](https://www.python.org/downloads).
 
 -   You manually modified your PATH Environment Variable incorrectly
 
-    If you added `Python` to PATH manually through environment variables, it is
-    possible that you only added the executable but not the `/Scripts` folder.
-    This would cause issues with `pip` and make command line tools not
+    If you added `Python` to PATH manually through environment variables, it is possible that you only added the
+    executable but not the `\Scripts` folder. This would cause issues with `pip` and make command line tools not
     accessible. Look at our [guide on adding Python to the
-    PATH](../python-on-windows.md#adding-python-to-your-path) for how to verify
-    and fix this.
+    PATH](../putting-python-on-path/#advanced-method-manually-edit-the-path) for how to verify and fix this.
 
-Projects that add a command line program usually work by adding an executable to
-the `/Scripts` folder of your Python install. If you clicked "Add to PATH" when
-installing Python this folder will have been added to PATH, so anything there
-should be runnable directly from the command line. This should also be the case
-when using a virtual environment, as long as it is properly activated.
+Projects that add a command line program usually work by adding an executable to the `\Scripts` folder of your Python
+install (the full path of which is `C:\Users\<user>\AppData\Local\Programs\Python\Python311\Scripts` in a default 3.11
+install). If you checked "Add python.exe to PATH" when installing Python, this folder will have been added to PATH, so
+anything there should be runnable directly from the command line. Virtual environments also have their own `\Scripts`
+directories that things can be installed to and are effectively on the PATH when the venv is properly activated.
 
 ### I get a `SyntaxError` when trying to run `pip`,`python`, or another command.
 
-When you type `python` in the terminal you enter into the python REPL
-(read-evaluate-print loop). This lets you run `Python` code line by line without
-having to create a file.
+When you type `python` in the terminal you enter into the python REPL ([read-evaluate-print
+loop](https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop)), also known as the Python console. This lets
+you run `Python` code line by line without having to create a file. You also may have opened a Python REPL by clicking
+on the Python App in your Start Menu.
 
-General commands like `pip` and `python` should be run in the terminal, not in
-the Python REPL. To exit the REPL, type `exit()` and press enter. You should
-then be able to run your commands normally.
+General commands like `pip` and `python` should be run in the normal terminal, not in the Python REPL. It usually has
+`>>>` at the start of each line. To exit the REPL, type `exit()` and press enter. You should then be able to run your
+commands normally, unless it was the Python App, in which case it will close completely and you'll need to open a
+terminal like PowerShell or Command Prompt separately.
 
 ### I tried to uninstall Python by deleting the folder, now it doesn't work and I can't reinstall it!
 
-You should never uninstall your Python installation by deleting the folder it is
-in. If you have, you may need to edit Registry Keys to fully remove the
-installation. Doing this is dangerous and beyond the scope of this guide.
+You should never uninstall your Python installation by deleting the folder it is in. If you have, you may need to edit
+Registry Keys to fully remove the installation. Doing this is dangerous and beyond the scope of this guide.
 
-To uninstall Python properly, run the installer for the version you want to
-uninstall and select "uninstall". If you no longer have the installer, you can
-re-download it first.
+To uninstall Python properly, run the installer for the version you want to uninstall and select "uninstall". If you no
+longer have the installer, you can [re-download it from python.org](https://www.python.org/downloads/windows/) first.