diff --git a/changelog.d/3292.docs.1.rst b/changelog.d/3292.docs.1.rst new file mode 100644 index 000000000..904642bee --- /dev/null +++ b/changelog.d/3292.docs.1.rst @@ -0,0 +1 @@ +Ensure development builds are not advertised to the wrong audience diff --git a/changelog.d/3292.docs.2.rst b/changelog.d/3292.docs.2.rst new file mode 100644 index 000000000..28d501420 --- /dev/null +++ b/changelog.d/3292.docs.2.rst @@ -0,0 +1 @@ +Clarify usage intent of some chat formatting functions diff --git a/docs/guide_cog_creation.rst b/docs/guide_cog_creation.rst index 50f7bc397..6ea670829 100644 --- a/docs/guide_cog_creation.rst +++ b/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` - - Develop Version: :code:`python3.7 -m pip install -U git+https://github.com/Cog-Creators/Red-DiscordBot@V3/develop#egg=Red-DiscordBot` + Stable Version: :code:`python3.8 -m pip install -U 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 diff --git a/docs/install_linux_mac.rst b/docs/install_linux_mac.rst index f89770542..4e6d9ebaa 100644 --- a/docs/install_linux_mac.rst +++ b/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 diff --git a/docs/install_windows.rst b/docs/install_windows.rst index a7cd41e99..93e390863 100644 --- a/docs/install_windows.rst +++ b/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 diff --git a/redbot/core/utils/chat_formatting.py b/redbot/core/utils/chat_formatting.py index 6c4c8d203..fe85cd1f3 100644 --- a/redbot/core/utils/chat_formatting.py +++ b/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