Use sphinx-prompt extension (#4908)

* Use sphinx-prompt extension

* Update PM2 guide

* Use an actual proper way to run Red with PM2

* Fix pm2 docs

Co-authored-by: Kowlin <Kowlin@users.noreply.github.com>

docs/autostart_pm2.rst

@@ -12,39 +12,37 @@ Installing PM2
 
 Start by installing Node.JS and NPM via your favorite package distributor. From there run the following command:
 
-:code:`npm install pm2 -g`
+.. prompt:: bash
+
+    npm install pm2 -g
 
 After PM2 is installed, run the following command to enable your Red instance to be managed by PM2. Replace the brackets with the required information.
-You can add additional Red based arguments after the instance, such as :code:`--dev`.
+You can add additional Red based arguments after the instance name, such as :code:`--dev`.
 
-.. code-block:: none
+.. prompt:: bash
 
-    pm2 start redbot --name "<Insert a name here>" --interpreter "<Location to your Python Interpreter>" --interpreter-args "-O" -- <Red Instance> --no-prompt
+    pm2 start "<path>" --name "<app_name>" -- -O -m redbot <instance_name> --no-prompt
 
-.. code-block:: none
+**Arguments to replace**
 
-    Arguments to replace.
+- ``<app_name>`` - A name to identify the bot within pm2, this is not your Red instance.
 
-    <Insert a name here>
+- | ``<path>`` - The location of your Python interpreter.
-    A name to identify the bot within pm2, this is not your Red instance.
+  | To find out where that is, use the proper set of commands:
 
-    <Location to your Python Interpreter>
+  .. prompt:: bash
-    The location of your Python interpreter, to find out where that is use the following command inside activated venv:
+      :prompts: $,(redenv) $
-    which python
+      :modifiers: auto
 
-    <Red Instance>
+      # If redbot is installed in a venv
-    The name of your Red instance.
+      $ source ~/redenv/bin/activate
+      (redenv) $ which python
 
-If you used :code:`pyenv virtualenv` to create your virtual environment, please make the following changes to the above generated command
+      # If redbot is installed in a pyenv virtualenv
+      $ pyenv shell <virtualenv_name>
+      (redenv) $ pyenv which python
 
-.. code-block:: none
+- ``<instance_name>`` - The name of your Red instance.
-
-    <Location to your Python Interpreter>
-    Run the following instead to get your Python interpreter
-    pyenv which python
-
-    Replace the `redbot` part of `pm2 start redbot` with the output of the following (when ran inside your activated venv)
-    pyenv which redbot
 
 ------------------------------
 Ensuring that PM2 stays online
@@ -52,4 +50,7 @@ Ensuring that PM2 stays online
 
 To make sure that PM2 stays online and persistence between machine restarts, run the following commands:
 
-:code:`pm2 save` & :code:`pm2 startup`
+.. prompt:: bash
+
+    pm2 save
+    pm2 startup

docs/autostart_systemd.rst

@@ -14,21 +14,23 @@ In order to create the service file, you will first need to know two things, you
 
 First, your Linux :code:`username` can be fetched with the following command:
 
-.. code-block:: bash
+.. prompt:: bash
 
     whoami
 
 Next, your python :code:`path` can be fetched with the following commands:
 
-.. code-block:: bash
+.. prompt:: bash
+    :prompts: $,(redenv) $
+    :modifiers: auto
 
     # If redbot is installed in a venv
-    source ~/redenv/bin/activate
+    $ source ~/redenv/bin/activate
-    which python
+    (redenv) $ which python
 
     # If redbot is installed in a pyenv virtualenv
-    pyenv shell <virtualenv_name>
+    $ pyenv shell <virtualenv_name>
-    pyenv which python
+    (redenv) $ pyenv which python
 
 Then create the new service file:
 
@@ -67,20 +69,28 @@ Starting and enabling the service
 
 To start the bot, run the service and add the instance name after the **@**:
 
-:code:`sudo systemctl start red@instancename`
+.. prompt:: bash
+
+    sudo systemctl start red@instancename
 
 To set the bot to start on boot, you must enable the service, again adding the instance name after the **@**:
 
-:code:`sudo systemctl enable red@instancename`
+.. prompt:: bash
+
+    sudo systemctl enable red@instancename
 
 If you need to shutdown the bot, you can use the ``[p]shutdown`` command or
 type the following command in the terminal, still by adding the instance name after the **@**:
 
-:code:`sudo systemctl stop red@instancename`
+.. prompt:: bash
+
+    sudo systemctl stop red@instancename
 
 .. warning:: If the service doesn't stop in the next 10 seconds, the process is killed.
     Check your logs to know the cause of the error that prevents the shutdown.
 
 To view Red’s log, you can acccess through journalctl:
 
-:code:`sudo journalctl -eu red@instancename`
+.. prompt:: bash
+
+    sudo journalctl -eu red@instancename

docs/conf.py

@@ -43,6 +43,7 @@ extensions = [
     "sphinx.ext.napoleon",
     "sphinx.ext.doctest",
     "sphinxcontrib_trio",
+    "sphinx-prompt",
     "deprecated_removed",
 ]
 

docs/install_linux_mac.rst

@@ -45,7 +45,7 @@ Arch Linux
     Latest Python packages for Arch Linux provide Python 3.9 which Red does not currently support.
     To use Red on Arch Linux, you will need to install latest version of Python 3.8 on your own.
 
-.. code-block:: none
+.. prompt:: bash
 
     sudo pacman -Syu python python-pip git jre11-openjdk-headless base-devel nano
 
@@ -60,7 +60,7 @@ Continue by `creating-venv-linux`.
 CentOS and RHEL 7
 ~~~~~~~~~~~~~~~~~
 
-.. code-block:: none
+.. prompt:: bash
 
     sudo yum -y groupinstall development
     sudo yum -y install zlib-devel bzip2 bzip2-devel readline-devel sqlite sqlite-devel openssl-devel xz xz-devel tk-devel libffi-devel findutils java-11-openjdk-headless nano
@@ -71,7 +71,7 @@ CentOS and RHEL 7
 
 In order to install Git 2.11 or greater, we recommend adding the IUS repository:
 
-.. code-block:: none
+.. prompt:: bash
 
     sudo yum -y install https://repo.ius.io/ius-release-el7.rpm
     sudo yum -y swap git git224
@@ -87,7 +87,7 @@ Complete the rest of the installation by `installing Python 3.8 with pyenv <inst
 CentOS and RHEL 8
 ~~~~~~~~~~~~~~~~~
 
-.. code-block:: none
+.. prompt:: bash
 
     sudo yum -y install epel-release
     sudo yum -y update
@@ -108,7 +108,7 @@ Debian and Raspbian Buster
 We recommend installing pyenv as a method of installing non-native versions of python on
 Debian/Raspbian Buster. This guide will tell you how. First, run the following commands:
 
-.. code-block:: none
+.. prompt:: bash
 
     sudo apt update
     sudo apt -y install make build-essential libssl-dev zlib1g-dev libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm libncurses5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev libgdbm-dev uuid-dev python3-openssl git openjdk-11-jre-headless nano
@@ -127,7 +127,7 @@ Fedora Linux
 Fedora Linux 32 and above has all required packages available in official repositories. Install
 them with dnf:
 
-.. code-block:: none
+.. prompt:: bash
 
     sudo dnf -y install python38 git java-11-openjdk-headless @development-tools nano
 
@@ -144,14 +144,14 @@ Mac
 Install Brew: in Finder or Spotlight, search for and open *Terminal*. In the terminal, paste the
 following, then press Enter:
 
-.. code-block:: none
+.. prompt:: bash
 
     /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
 
 After the installation, install the required packages by pasting the commands and pressing enter,
 one-by-one:
 
-.. code-block:: none
+.. prompt:: bash
 
     brew install python@3.8
     echo 'export PATH="/usr/local/opt/python@3.8/bin:$PATH"' >> ~/.profile
@@ -177,7 +177,7 @@ be installed to the ``/opt`` directory.
 
 First, add the Opt-Python community repository:
 
-.. code-block:: none
+.. prompt:: bash
 
     source /etc/os-release
     sudo zypper -n ar -f https://download.opensuse.org/repositories/home:/Rotkraut:/Opt-Python/openSUSE_Leap_${VERSION_ID}/ Opt-Python
@@ -185,7 +185,7 @@ First, add the Opt-Python community repository:
 
 Now install the pre-requirements with zypper:
 
-.. code-block:: none
+.. prompt:: bash
 
     sudo zypper -n install opt-python38 opt-python38-setuptools git-core java-11-openjdk-headless nano
     sudo zypper -n install -t pattern devel_basis
@@ -193,14 +193,14 @@ Now install the pre-requirements with zypper:
 Since Python is now installed to ``/opt/python``, we should add it to PATH. You can add a file in
 ``/etc/profile.d/`` to do this:
 
-.. code-block:: none
+.. prompt:: bash
 
     echo 'export PATH="/opt/python/bin:$PATH"' | sudo tee /etc/profile.d/opt-python.sh
     source /etc/profile.d/opt-python.sh
 
 Now, install pip with easy_install:
 
-.. code-block:: none
+.. prompt:: bash
 
     sudo /opt/python/bin/easy_install-3.8 pip
 
@@ -212,7 +212,7 @@ openSUSE Tumbleweed
 openSUSE Tumbleweed has all required dependencies available in official repositories. Install them
 with zypper:
 
-.. code-block:: none
+.. prompt:: bash
 
     sudo zypper -n install python38-base python38-pip git-core java-11-openjdk-headless nano
     sudo zypper -n install -t pattern devel_basis
@@ -229,7 +229,7 @@ Ubuntu 18.04 LTS
 
 We recommend adding the ``git-core`` ppa to install Git 2.11 or greater:
 
-.. code-block:: none
+.. prompt:: bash
 
     sudo apt update
     sudo apt -y install software-properties-common
@@ -237,13 +237,13 @@ We recommend adding the ``git-core`` ppa to install Git 2.11 or greater:
 
 We recommend adding the ``deadsnakes`` ppa to install Python 3.8.1 or greater:
 
-.. code-block:: none
+.. prompt:: bash
 
     sudo add-apt-repository -y ppa:deadsnakes/ppa
 
 Now install the pre-requirements with apt:
 
-.. code-block:: none
+.. prompt:: bash
 
     sudo apt -y install python3.8 python3.8-dev python3.8-venv python3-pip git openjdk-11-jre-headless build-essential nano
 
@@ -259,7 +259,7 @@ Ubuntu 20.04 LTS
 
 We recommend adding the ``git-core`` ppa to install Git 2.11 or greater:
 
-.. code-block:: none
+.. prompt:: bash
 
     sudo apt update
     sudo apt -y install software-properties-common
@@ -267,7 +267,7 @@ We recommend adding the ``git-core`` ppa to install Git 2.11 or greater:
 
 Now install the pre-requirements with apt:
 
-.. code-block:: none
+.. prompt:: bash
 
     sudo apt -y install python3.8 python3.8-dev python3.8-venv python3-pip git openjdk-11-jre-headless build-essential nano
 
@@ -283,7 +283,7 @@ Ubuntu non-LTS versions
 
 We recommend adding the ``git-core`` ppa to install Git 2.11 or greater:
 
-.. code-block:: none
+.. prompt:: bash
 
     sudo apt update
     sudo apt -y install software-properties-common
@@ -292,7 +292,7 @@ We recommend adding the ``git-core`` ppa to install Git 2.11 or greater:
 Now, to install non-native version of python on non-LTS versions of Ubuntu, we recommend
 installing pyenv. To do this, first run the following commands:
 
-.. code-block:: none
+.. prompt:: bash
 
     sudo apt -y install make build-essential libssl-dev zlib1g-dev libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm libncurses5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev libgdbm-dev uuid-dev python3-openssl git openjdk-11-jre-headless nano
     CXX=/usr/bin/g++
@@ -316,7 +316,7 @@ On distributions where Python 3.8 needs to be compiled from source, we recommend
 This simplifies the compilation process and has the added bonus of simplifying setting up Red in a
 virtual environment.
 
-.. code-block:: none
+.. prompt:: bash
 
     command -v pyenv && pyenv update || curl https://pyenv.run | bash
 
@@ -325,7 +325,7 @@ instructions given to fix that, then close and reopen your shell.**
 
 Then run the following command:
 
-.. code-block:: none
+.. prompt:: bash
 
     CONFIGURE_OPTS=--enable-optimizations pyenv install 3.8.8 -v
 
@@ -337,7 +337,7 @@ slower.
 
 After that is finished, run:
 
-.. code-block:: none
+.. prompt:: bash
 
     pyenv global 3.8.8
 
@@ -377,11 +377,15 @@ First, choose a directory where you would like to create your virtual environmen
 to keep it in a location which is easy to type out the path to. From now, we'll call it
 ``redenv`` and it will be located in your home directory.
 
-Create your virtual environment with the following command::
+Create your virtual environment with the following command:
+
+.. prompt:: bash
 
     python3.8 -m venv ~/redenv
 
-And activate it with the following command::
+And activate it with the following command:
+
+.. prompt:: bash
 
     source ~/redenv/bin/activate
 
@@ -403,18 +407,24 @@ Using ``pyenv virtualenv``
 Using ``pyenv virtualenv`` saves you the headache of remembering where you installed your virtual
 environments. This option is only available if you installed Python with pyenv.
 
-First, ensure your pyenv interpreter is set to python 3.8.1 or greater with the following command::
+First, ensure your pyenv interpreter is set to python 3.8.1 or greater with the following command:
+
+.. prompt:: bash
 
     pyenv version
 
-Now, create a virtual environment with the following command::
+Now, create a virtual environment with the following command:
+
+.. prompt:: bash
 
     pyenv virtualenv <name>
 
 Replace ``<name>`` with whatever you like. If you ever forget what you named it,
 you can always use the command ``pyenv versions`` to list all virtual environments.
 
-Now activate your virtualenv with the following command::
+Now activate your virtualenv with the following command:
+
+.. prompt:: bash
 
     pyenv shell <name>
 
@@ -438,14 +448,16 @@ Choose one of the following commands to install Red.
 
 To install without additional config backend support:
 
-.. code-block:: none
+.. prompt:: bash
+    :prompts: (redenv) $
 
     python -m pip install -U pip setuptools wheel
     python -m pip install -U Red-DiscordBot
 
 Or, to install with PostgreSQL support:
 
-.. code-block:: none
+.. prompt:: bash
+    :prompts: (redenv) $
 
     python -m pip install -U pip setuptools wheel
     python -m pip install -U "Red-DiscordBot[postgres]"
@@ -461,7 +473,8 @@ Setting Up and Running Red
 
 After installation, set up your instance with the following command:
 
-.. code-block:: none
+.. prompt:: bash
+    :prompts: (redenv) $
 
     redbot-setup
 
@@ -471,7 +484,8 @@ running the bot).
 
 Once done setting up the instance, run the following command to run Red:
 
-.. code-block:: none
+.. prompt:: bash
+    :prompts: (redenv) $
 
     redbot <your instance name>
 

docs/install_windows.rst

@@ -33,7 +33,7 @@ right-click on it and then click "Run as administrator".
 
 Then run each of the following commands:
 
-.. code-block:: none
+.. prompt:: powershell
 
     Set-ExecutionPolicy Bypass -Scope Process -Force
     [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072
@@ -44,7 +44,7 @@ Then run each of the following commands:
 
 For Audio support, you should also run the following command before exiting:
 
-.. code-block:: none
+.. prompt:: powershell
 
     choco upgrade adoptopenjdk11jre -y
 
@@ -109,13 +109,13 @@ Start with opening a command prompt (open Start, search for "command prompt", th
 
 Then create your virtual environment with the following command
 
-.. code-block:: none
+.. prompt:: batch
 
     py -3.8 -m venv "%userprofile%\redenv"
 
 And activate it with the following command
 
-.. code-block:: none
+.. prompt:: batch
 
     "%userprofile%\redenv\Scripts\activate.bat"
 
@@ -138,14 +138,16 @@ Run **one** of the following set of commands, depending on what extras you want
 
   * Normal installation:
 
-    .. code-block:: none
+    .. prompt:: batch
+        :prompts: (redenv) C:\\>
 
         python -m pip install -U pip setuptools wheel
         python -m pip install -U Red-DiscordBot
 
   * With PostgreSQL support:
 
-    .. code-block:: none
+    .. prompt:: batch
+        :prompts: (redenv) C:\\>
 
         python -m pip install -U pip setuptools wheel
         python -m pip install -U Red-DiscordBot[postgres]
@@ -156,7 +158,8 @@ Setting Up and Running Red
 
 After installation, set up your instance with the following command:
 
-.. code-block:: none
+.. prompt:: batch
+    :prompts: (redenv) C:\\>
 
     redbot-setup
 
@@ -166,7 +169,8 @@ running the bot).
 
 Once done setting up the instance, run the following command to run Red:
 
-.. code-block:: none
+.. prompt:: batch
+    :prompts: (redenv) C:\\>
 
     redbot <your instance name>
 

docs/update_red.rst

@@ -37,13 +37,14 @@ If you have Red 3.2.0 or newer, you can upgrade by following these 4 easy steps:
 
 2. Activate your venv with the following command:
 
-    .. code:: none
+    .. prompt:: batch
 
         "%userprofile%\redenv\Scripts\activate.bat"
 
 3. Update Red with this command:
 
-    .. code:: none
+    .. prompt:: batch
+        :prompts: (redenv) C:\\>
 
         python -m pip install -U Red-DiscordBot
 
@@ -64,19 +65,20 @@ If you have Red 3.2.0 or newer, you can upgrade by following these 4 easy steps:
   
     If you used ``venv`` for your virtual environment, use:
 
-    .. code:: none
+    .. prompt:: bash
 
         source ~/redenv/bin/activate
 
     If you used ``pyenv`` for your virtual environment, use:
 
-    .. code:: none
+    .. prompt:: bash
 
         pyenv shell <name>
 
 3. Update Red with this command:
 
-    .. code:: none
+    .. prompt:: bash
+        :prompts: (redenv) $
 
         python -m pip install -U Red-DiscordBot
 
@@ -107,7 +109,8 @@ Follow every step to ensure you have all dependencies up-to-date and only skip `
      - If you were using the MongoDB driver, **prior to launching your instance after update**,
        you will need to run the following commands to convert:
 
-         .. code::
+         .. prompt:: bash
+           :prompts: (redenv) $
 
            python -m pip install dnspython~=1.16.0 motor~=2.0.0 pymongo~=3.8.0
            redbot-setup convert [instancename] json
@@ -125,7 +128,8 @@ Red 3.0.2 and older
      - If you were using the MongoDB driver, **prior to updating**, you will need to convert your data to JSON backend,
        using following command:
 
-         .. code::
+         .. prompt:: bash
+           :prompts: (redenv) $
 
            redbot-setup --edit
 

setup.cfg

@@ -78,6 +78,7 @@ docs =
     requests==2.25.1
     snowballstemmer==2.1.0
     Sphinx==3.4.3
+    sphinx-prompt==1.4.0
     sphinx-rtd-theme==0.5.1
     sphinxcontrib-applehelp==1.0.2
     sphinxcontrib-devhelp==1.0.2

tools/primary_deps.ini

@@ -30,6 +30,7 @@ install_requires =
 [options.extras_require]
 docs =
     Sphinx
+    sphinx-prompt
     sphinx_rtd_theme
     sphinxcontrib-trio
 postgres =