[3.2.0 Docs] Some clarifications (#3292)

* docs

*  changelog

* Fix python for choco

* k

* little more

changelog.d/3292.docs.1.rst

@@ -0,0 +1 @@
+Ensure development builds are not advertised to the wrong audience

changelog.d/3292.docs.2.rst

@@ -0,0 +1 @@
+Clarify usage intent of some chat formatting functions

docs/guide_cog_creation.rst

@@ -17,7 +17,7 @@ you in the process.
 Getting started
 ---------------
 
-To start off, be sure that you have installed Python 3.7.
+To start off, be sure that you have installed Python 3.8.
 Next, you need to decide if you want to develop against the Stable or Develop version of Red.
 Depending on what your goal is should help determine which version you need.
 
@@ -26,11 +26,24 @@ Depending on what your goal is should help determine which version you need.
     If your goal is to support both versions, make sure you build compatibility layers or use separate branches to keep compatibility until the next Red release
 
 Open a terminal or command prompt and type one of the following
-    Stable Version: :code:`python3.7 -m pip install -U Red-DiscordBot`
+    Stable Version: :code:`python3.8 -m pip install -U Red-DiscordBot`
-    
-    Develop Version: :code:`python3.7 -m pip install -U git+https://github.com/Cog-Creators/Red-DiscordBot@V3/develop#egg=Red-DiscordBot`
 
-(Windows users may need to use :code:`py -3.7` or :code:`python` instead of :code:`python3.7`)
+.. note::
+
+  To install the development version, replace ``Red-DiscordBot`` in the above commands with the
+  link below. **The development version of the bot contains experimental changes. It is not
+  intended for normal users.** We will not support anyone using the development version in any
+  support channels. Using the development version may break third party cogs and not all core
+  commands may work. Downgrading to stable after installing the development version may cause
+  data loss, crashes or worse. Please keep this in mind when using the Development version
+  While working on cog creation.
+
+  .. code-block:: none
+
+      git+https://github.com/Cog-Creators/Red-DiscordBot@V3/develop#egg=Red-DiscordBot
+
+
+(Windows users may need to use :code:`py -3.8` or :code:`python` instead of :code:`python3.8`)
 
 --------------------
 Setting up a package

docs/install_linux_mac.rst

@@ -279,18 +279,6 @@ Or, to install with PostgreSQL support:
     python3.8 -m pip install -U setuptools wheel
     python3.8 -m pip install -U Red-DiscordBot[postgres]
 
-.. note::
-
-  To install the development version, replace ``Red-DiscordBot`` in the above commands with the
-  link below. **The development version of the bot contains experimental changes. It is not
-  intended for normal users.** We will not support anyone using the development version in any
-  support channels. Using the development version may break third party cogs and not all core
-  commands may work. Downgrading to stable after installing the development version may cause
-  data loss, crashes or worse.
-
-  .. code-block:: none
-
-      git+https://github.com/Cog-Creators/Red-DiscordBot@V3/develop#egg=Red-DiscordBot
 
 --------------------------
 Setting Up and Running Red

docs/install_windows.rst

@@ -28,7 +28,7 @@ Then run each of the following commands:
     iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))
     choco install git --params "/GitOnlyOnPath /WindowsTerminal" -y
     choco install visualstudio2019-workload-vctools -y
-    choco install python3 --version=3.8.1 -y
+    choco install python3 -y
 
 For Audio support, you should also run the following command before exiting:
 
@@ -99,18 +99,6 @@ Installing Red
         python -m pip install -U setuptools wheel
         python -m pip install -U Red-DiscordBot[postgres]
 
-  .. note::
-
-      To install the development version, replace ``Red-DiscordBot`` in the above commands with the
-      link below. **The development version of the bot contains experimental changes. It is not
-      intended for normal users.** We will not support anyone using the development version in any
-      support channels. Using the development version may break third party cogs and not all core
-      commands may work. Downgrading to stable after installing the development version may cause
-      data loss, crashes or worse.
-
-      .. code-block:: none
-
-          git+https://github.com/Cog-Creators/Red-DiscordBot@V3/develop#egg=Red-DiscordBot
 
 --------------------------
 Setting Up and Running Red

redbot/core/utils/chat_formatting.py

@@ -63,6 +63,8 @@ def question(text: str) -> str:
 def bold(text: str) -> str:
     """Get the given text in bold.
 
+    Note: This escapes text prior to bolding.
+
     Parameters
     ----------
     text : str
@@ -121,6 +123,8 @@ def inline(text: str) -> str:
 def italics(text: str) -> str:
     """Get the given text in italics.
 
+    Note: This escapes text prior to italicising
+
     Parameters
     ----------
     text : str
@@ -277,6 +281,8 @@ def pagify(
 def strikethrough(text: str) -> str:
     """Get the given text with a strikethrough.
 
+    Note: This escapes text prior to applying a strikethrough
+
     Parameters
     ----------
     text : str
@@ -295,6 +301,8 @@ def strikethrough(text: str) -> str:
 def underline(text: str) -> str:
     """Get the given text with an underline.
 
+    Note: This escapes text prior to underlining
+
     Parameters
     ----------
     text : str
@@ -332,7 +340,7 @@ def escape(text: str, *, mass_mentions: bool = False, formatting: bool = False)
         text = text.replace("@everyone", "@\u200beveryone")
         text = text.replace("@here", "@\u200bhere")
     if formatting:
-        text = text.replace("`", "\\`").replace("*", "\\*").replace("_", "\\_").replace("~", "\\~")
+        text = discord.utils.escape_markdown(text)
     return text