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>
2025-11-07 03:38:53 -05:00 · 2021-04-03 18:52:11 +02:00 · 2021-04-03 18:52:11 +02:00 · 0becf70b05
commit 0becf70b05
parent 0144cbf88b
8 changed files with 116 additions and 80 deletions
--- a/docs/autostart_pm2.rst
+++ b/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>
-    A name to identify the bot within pm2, this is not your Red instance.
+- | ``<path>`` - The location of your Python interpreter.
+  | To find out where that is, use the proper set of commands:

-    <Location to your Python Interpreter>
-    The location of your Python interpreter, to find out where that is use the following command inside activated venv:
-    which python
+  .. prompt:: bash
+      :prompts: $,(redenv) $
+      :modifiers: auto

-    <Red Instance>
-    The name of your Red instance.
+      # If redbot is installed in a venv
+      $ 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
-
-    <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
+- ``<instance_name>`` - The name of your Red instance.

 ------------------------------
 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
--- a/docs/autostart_systemd.rst
+++ b/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
-    which python
+    $ source ~/redenv/bin/activate
+    (redenv) $ which python

    # If redbot is installed in a pyenv virtualenv
-    pyenv shell <virtualenv_name>
-    pyenv which python
+    $ pyenv shell <virtualenv_name>
+    (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
--- a/docs/conf.py
+++ b/docs/conf.py
@ -43,6 +43,7 @@ extensions = [
    "sphinx.ext.napoleon",
    "sphinx.ext.doctest",
    "sphinxcontrib_trio",
+    "sphinx-prompt",
    "deprecated_removed",
 ]

--- a/docs/install_linux_mac.rst
+++ b/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>

--- a/docs/install_windows.rst
+++ b/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>

--- a/docs/update_red.rst
+++ b/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

--- a/setup.cfg
+++ b/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
--- a/tools/primary_deps.ini
+++ b/tools/primary_deps.ini
@ -30,6 +30,7 @@ install_requires =
 [options.extras_require]
 docs =
    Sphinx
+    sphinx-prompt
    sphinx_rtd_theme
    sphinxcontrib-trio
 postgres =