Add command switch tabs for Bash, CMD and Powershell with sphinx-tabs (#3714)

* Enable Sphinx extension sphinx-tabs

* Add command tabs for all export commands

* Add command tabs for all venv commands

Fix trim spaces

CONTRIBUTING.rst

@@ -96,15 +96,20 @@ First time setup
 
 -   Create a virtualenv.
 
+    .. tabs::
+
+       .. group-tab:: macOS/Linux
+
           .. code-block:: text
 
              $ python3 -m venv env
              $ . env/bin/activate
 
-    On Windows, activating is different.
+       .. group-tab:: Windows
 
           .. code-block:: text
 
+             > py -3 -m venv env
              > env\Scripts\activate
 
 -   Install Flask in editable mode with development dependencies.

docs/cli.rst

@@ -18,17 +18,25 @@ The ``flask`` command is installed by Flask, not your application; it must be
 told where to find your application in order to use it. The ``FLASK_APP``
 environment variable is used to specify how to load the application.
 
-Unix Bash (Linux, Mac, etc.)::
+.. tabs::
+
+   .. group-tab:: Bash
+
+      .. code-block:: text
 
          $ export FLASK_APP=hello
          $ flask run
 
-Windows CMD::
+   .. group-tab:: CMD
+
+      .. code-block:: text
 
          > set FLASK_APP=hello
          > flask run
 
-Windows PowerShell::
+   .. group-tab:: Powershell
+
+      .. code-block:: text
 
          > $env:FLASK_APP = "hello"
          > flask run
@@ -128,9 +136,42 @@ If the env is set to ``development``, the ``flask`` command will enable
 debug mode and ``flask run`` will enable the interactive debugger and
 reloader.
 
-::
+.. tabs::
 
-    $ FLASK_ENV=development flask run
+   .. group-tab:: Bash
+
+      .. code-block:: text
+
+         $ export FLASK_ENV=development
+         $ flask run
+          * Serving Flask app "hello"
+          * Environment: development
+          * Debug mode: on
+          * Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)
+          * Restarting with inotify reloader
+          * Debugger is active!
+          * Debugger PIN: 223-456-919
+
+   .. group-tab:: CMD
+
+      .. code-block:: text
+
+         > set FLASK_ENV=development
+         > flask run
+          * Serving Flask app "hello"
+          * Environment: development
+          * Debug mode: on
+          * Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)
+          * Restarting with inotify reloader
+          * Debugger is active!
+          * Debugger PIN: 223-456-919
+
+   .. group-tab:: Powershell
+
+      .. code-block:: text
+
+         > $env:FLASK_ENV = "development"
+         > flask run
           * Serving Flask app "hello"
           * Environment: development
           * Debug mode: on
@@ -149,7 +190,11 @@ additional files with the ``--extra-files`` option, or the
 ``FLASK_RUN_EXTRA_FILES`` environment variable. Multiple paths are
 separated with ``:``, or ``;`` on Windows.
 
-.. code-block:: none
+.. tabs::
+
+   .. group-tab:: Bash
+
+      .. code-block:: text
 
           $ flask run --extra-files file1:dirA/file2:dirB/
           # or
@@ -158,6 +203,28 @@ separated with ``:``, or ``;`` on Windows.
            * Running on http://127.0.0.1:8000/
            * Detected change in '/path/to/file1', reloading
 
+   .. group-tab:: CMD
+
+      .. code-block:: text
+
+          > flask run --extra-files file1:dirA/file2:dirB/
+          # or
+          > set FLASK_RUN_EXTRA_FILES=file1:dirA/file2:dirB/
+          > flask run
+           * Running on http://127.0.0.1:8000/
+           * Detected change in '/path/to/file1', reloading
+
+   .. group-tab:: Powershell
+
+      .. code-block:: text
+
+          > flask run --extra-files file1:dirA/file2:dirB/
+          # or
+          > $env:FLASK_RUN_EXTRA_FILES = "file1:dirA/file2:dirB/"
+          > flask run
+           * Running on http://127.0.0.1:8000/
+           * Detected change in '/path/to/file1', reloading
+
 
 Debug Mode
 ----------
@@ -206,12 +273,32 @@ environment variables. The variables use the pattern
 ``FLASK_COMMAND_OPTION``. For example, to set the port for the run
 command, instead of ``flask run --port 8000``:
 
-.. code-block:: bash
+.. tabs::
+
+   .. group-tab:: Bash
+
+      .. code-block:: text
 
          $ export FLASK_RUN_PORT=8000
          $ flask run
           * Running on http://127.0.0.1:8000/
 
+   .. group-tab:: CMD
+
+      .. code-block:: text
+
+         > set FLASK_RUN_PORT=8000
+         > flask run
+          * Running on http://127.0.0.1:8000/
+
+   .. group-tab:: Powershell
+
+      .. code-block:: text
+
+         > $env:FLASK_RUN_PORT = 8000
+         > flask run
+          * Running on http://127.0.0.1:8000/
+
 These can be added to the ``.flaskenv`` file just like ``FLASK_APP`` to
 control default command options.
 
@@ -234,11 +321,29 @@ a project runner that loads them already. Keep in mind that the
 environment variables must be set before the app loads or it won't
 configure as expected.
 
-.. code-block:: bash
+.. tabs::
+
+   .. group-tab:: Bash
+
+      .. code-block:: text
 
          $ export FLASK_SKIP_DOTENV=1
          $ flask run
 
+   .. group-tab:: CMD
+
+      .. code-block:: text
+
+         > set FLASK_SKIP_DOTENV=1
+         > flask run
+
+   .. group-tab:: Powershell
+
+      .. code-block:: text
+
+         > $env:FLASK_SKIP_DOTENV = 1
+         > flask run
+
 
 Environment Variables From virtualenv
 -------------------------------------
@@ -247,14 +352,26 @@ If you do not want to install dotenv support, you can still set environment
 variables by adding them to the end of the virtualenv's :file:`activate`
 script. Activating the virtualenv will set the variables.
 
-Unix Bash, :file:`venv/bin/activate`::
+.. tabs::
+
+   .. group-tab:: Bash
+
+      Unix Bash, :file:`venv/bin/activate`::
 
           $ export FLASK_APP=hello
 
-Windows CMD, :file:`venv\\Scripts\\activate.bat`::
+   .. group-tab:: CMD
+
+      Windows CMD, :file:`venv\\Scripts\\activate.bat`::
 
           > set FLASK_APP=hello
 
+   .. group-tab:: Powershell
+
+      Windows Powershell, :file:`venv\\Scripts\\activate.ps1`::
+
+          > $env:FLASK_APP = "hello"
+
 It is preferred to use dotenv support over this, since :file:`.flaskenv` can be
 committed to the repository so that it works automatically wherever the project
 is checked out.

docs/conf.py

@@ -18,6 +18,7 @@ extensions = [
     "sphinxcontrib.log_cabinet",
     "pallets_sphinx_themes",
     "sphinx_issues",
+    "sphinx_tabs.tabs",
 ]
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3/", None),

docs/config.rst

@@ -65,12 +65,30 @@ in debug mode. To control this separately from the environment, use the
     from debug mode. The development environment enables debug mode.
 
 To switch Flask to the development environment and enable debug mode,
-set :envvar:`FLASK_ENV`::
+set :envvar:`FLASK_ENV`:
+
+.. tabs::
+
+   .. group-tab:: Bash
+
+      .. code-block:: text
 
          $ export FLASK_ENV=development
          $ flask run
 
-(On Windows, use ``set`` instead of ``export``.)
+   .. group-tab:: CMD
+
+      .. code-block:: text
+
+         > set FLASK_ENV=development
+         > flask run
+
+   .. group-tab:: Powershell
+
+      .. code-block:: text
+
+         > $env:FLASK_ENV = "development"
+         > flask run
 
 Using the environment variables as described above is recommended. While
 it is possible to set :data:`ENV` and :data:`DEBUG` in your config or
@@ -409,18 +427,34 @@ So a common pattern is this::
 This first loads the configuration from the
 `yourapplication.default_settings` module and then overrides the values
 with the contents of the file the :envvar:`YOURAPPLICATION_SETTINGS`
-environment variable points to.  This environment variable can be set on
+environment variable points to.  This environment variable can be set
-Linux or OS X with the export command in the shell before starting the
+in the shell before starting the server:
-server::
+
+.. tabs::
+
+   .. group-tab:: Bash
+
+      .. code-block:: text
 
          $ export YOURAPPLICATION_SETTINGS=/path/to/settings.cfg
-    $ python run-app.py
+         $ flask run
           * Running on http://127.0.0.1:5000/
-     * Restarting with reloader...
 
-On Windows systems use the `set` builtin instead::
+   .. group-tab:: CMD
+
+      .. code-block:: text
 
          > set YOURAPPLICATION_SETTINGS=\path\to\settings.cfg
+         > flask run
+          * Running on http://127.0.0.1:5000/
+
+   .. group-tab:: Powershell
+
+      .. code-block:: text
+
+         > $env:YOURAPPLICATION_SETTINGS = "\path\to\settings.cfg"
+         > flask run
+          * Running on http://127.0.0.1:5000/
 
 The configuration files themselves are actual Python files.  Only values
 in uppercase are actually stored in the config object later on.  So make
@@ -465,17 +499,36 @@ In addition to pointing to configuration files using environment variables, you
 may find it useful (or necessary) to control your configuration values directly
 from the environment.
 
-Environment variables can be set on Linux or OS X with the export command in
+Environment variables can be set in the shell before starting the server:
-the shell before starting the server::
 
-    $ export SECRET_KEY='5f352379324c22463451387a0aec5d2f'
+.. tabs::
+
+   .. group-tab:: Bash
+
+      .. code-block:: text
+
+         $ export SECRET_KEY="5f352379324c22463451387a0aec5d2f"
          $ export MAIL_ENABLED=false
-    $ python run-app.py
+         $ flask run
           * Running on http://127.0.0.1:5000/
 
-On Windows systems use the ``set`` builtin instead::
+   .. group-tab:: CMD
 
-    > set SECRET_KEY='5f352379324c22463451387a0aec5d2f'
+      .. code-block:: text
+
+         > set SECRET_KEY="5f352379324c22463451387a0aec5d2f"
+         > set MAIL_ENABLED=false
+         > flask run
+          * Running on http://127.0.0.1:5000/
+
+   .. group-tab:: Powershell
+
+      .. code-block:: text
+
+         > $env:SECRET_KEY = "5f352379324c22463451387a0aec5d2f"
+         > $env:MAIL_ENABLED = "false"
+         > flask run
+          * Running on http://127.0.0.1:5000/
 
 While this approach is straightforward to use, it is important to remember that
 environment variables are strings -- they are not automatically deserialized

docs/debugging.rst

@@ -44,11 +44,29 @@ To enable the debugger, run the development server with the
 Flask in debug mode, which changes how it handles some errors, and
 enables the debugger and reloader.
 
-.. code-block:: text
+.. tabs::
+
+   .. group-tab:: Bash
+
+      .. code-block:: text
 
          $ export FLASK_ENV=development
          $ flask run
 
+   .. group-tab:: CMD
+
+      .. code-block:: text
+
+         > set FLASK_ENV=development
+         > flask run
+
+   .. group-tab:: Powershell
+
+      .. code-block:: text
+
+         > $env:FLASK_ENV = "development"
+         > flask run
+
 ``FLASK_ENV`` can only be set as an environment variable. When running
 from Python code, passing ``debug=True`` enables debug mode, which is
 mostly equivalent. Debug mode can be controled separately from
@@ -79,11 +97,29 @@ which can interfere.
 
 When running from the command line:
 
-.. code-block:: text
+.. tabs::
+
+   .. group-tab:: Bash
+
+      .. code-block:: text
 
          $ export FLASK_ENV=development
          $ flask run --no-debugger --no-reload
 
+   .. group-tab:: CMD
+
+      .. code-block:: text
+
+         > set FLASK_ENV=development
+         > flask run --no-debugger --no-reload
+
+   .. group-tab:: Powershell
+
+      .. code-block:: text
+
+         > $env:FLASK_ENV = "development"
+         > flask run --no-debugger --no-reload
+
 When running from Python:
 
 .. code-block:: python

docs/installation.rst

@@ -75,17 +75,23 @@ Create an environment
 
 Create a project folder and a :file:`venv` folder within:
 
-.. code-block:: sh
+.. tabs::
+
+   .. group-tab:: macOS/Linux
+
+      .. code-block:: text
 
          $ mkdir myproject
          $ cd myproject
          $ python3 -m venv venv
 
-On Windows:
+   .. group-tab:: Windows
 
-.. code-block:: bat
+      .. code-block:: text
 
-    $ py -3 -m venv venv
+         > mkdir myproject
+         > cd myproject
+         > py -3 -m venv venv
 
 
 .. _install-activate-env:
@@ -95,13 +101,17 @@ Activate the environment
 
 Before you work on your project, activate the corresponding environment:
 
-.. code-block:: sh
+.. tabs::
+
+   .. group-tab:: macOS/Linux
+
+      .. code-block:: text
 
          $ . venv/bin/activate
 
-On Windows:
+   .. group-tab:: Windows
 
-.. code-block:: bat
+      .. code-block:: text
 
          > venv\Scripts\activate
 

docs/patterns/appfactories.rst

@@ -87,17 +87,57 @@ For more information about the design of extensions refer to :doc:`/extensiondev
 Using Applications
 ------------------
 
-To run such an application, you can use the :command:`flask` command::
+To run such an application, you can use the :command:`flask` command:
+
+.. tabs::
+
+   .. group-tab:: Bash
+
+      .. code-block:: text
 
          $ export FLASK_APP=myapp
          $ flask run
 
+   .. group-tab:: CMD
+
+      .. code-block:: text
+
+         > set FLASK_APP=myapp
+         > flask run
+
+   .. group-tab:: Powershell
+
+      .. code-block:: text
+
+         > $env:FLASK_APP = "myapp"
+         > flask run
+
 Flask will automatically detect the factory (``create_app`` or ``make_app``)
-in ``myapp``. You can also pass arguments to the factory like this::
+in ``myapp``. You can also pass arguments to the factory like this:
+
+.. tabs::
+
+   .. group-tab:: Bash
+
+      .. code-block:: text
 
          $ export FLASK_APP="myapp:create_app('dev')"
          $ flask run
 
+   .. group-tab:: CMD
+
+      .. code-block:: text
+
+         > set FLASK_APP="myapp:create_app('dev')"
+         > flask run
+
+   .. group-tab:: Powershell
+
+      .. code-block:: text
+
+         > $env:FLASK_APP = "myapp:create_app('dev')"
+         > flask run
+
 Then the ``create_app`` factory in ``myapp`` is called with the string
 ``'dev'`` as the argument. See :doc:`/cli` for more detail.
 

docs/patterns/packages.rst

@@ -57,16 +57,52 @@ a big problem, just add a new file called :file:`setup.py` next to the inner
     )
 
 In order to run the application you need to export an environment variable
-that tells Flask where to find the application instance::
+that tells Flask where to find the application instance:
+
+.. tabs::
+
+   .. group-tab:: Bash
+
+      .. code-block:: text
 
          $ export FLASK_APP=yourapplication
 
+   .. group-tab:: CMD
+
+      .. code-block:: text
+
+         > set FLASK_APP=yourapplication
+
+   .. group-tab:: Powershell
+
+      .. code-block:: text
+
+         > $env:FLASK_APP = "yourapplication"
+
 If you are outside of the project directory make sure to provide the exact
 path to your application directory. Similarly you can turn on the
-development features like this::
+development features like this:
+
+.. tabs::
+
+   .. group-tab:: Bash
+
+      .. code-block:: text
 
          $ export FLASK_ENV=development
 
+   .. group-tab:: CMD
+
+      .. code-block:: text
+
+         > set FLASK_ENV=development
+
+   .. group-tab:: Powershell
+
+      .. code-block:: text
+
+         > $env:FLASK_ENV = "development"
+
 In order to install and run the application you need to issue the following
 commands::
 

docs/quickstart.rst

@@ -44,20 +44,31 @@ To run the application, use the :command:`flask` command or
 to tell your terminal the application to work with by exporting the
 ``FLASK_APP`` environment variable:
 
-.. code-block:: text
+.. tabs::
+
+   .. group-tab:: Bash
+
+      .. code-block:: text
 
          $ export FLASK_APP=hello.py
          $ flask run
           * Running on http://127.0.0.1:5000/
 
-If you are on Windows, the environment variable syntax depends on command line
+   .. group-tab:: CMD
-interpreter. On Command Prompt::
 
-    C:\path\to\app>set FLASK_APP=hello.py
+      .. code-block:: text
 
-And on PowerShell::
+         > set FLASK_APP=hello.py
+         > flask run
+          * Running on http://127.0.0.1:5000/
 
-    PS C:\path\to\app> $env:FLASK_APP = "hello.py"
+   .. group-tab:: Powershell
+
+      .. code-block:: text
+
+         > $env:FLASK_APP = "hello.py"
+         > flask run
+          * Running on http://127.0.0.1:5000/
 
 This launches a very simple builtin server, which is good enough for
 testing but probably not what you want to use in production. For
@@ -135,11 +146,29 @@ error occurs during a request.
 To enable all development features, set the ``FLASK_ENV`` environment
 variable to ``development`` before calling ``flask run``.
 
-.. code-block:: text
+.. tabs::
+
+   .. group-tab:: Bash
+
+      .. code-block:: text
 
          $ export FLASK_ENV=development
          $ flask run
 
+   .. group-tab:: CMD
+
+      .. code-block:: text
+
+         > set FLASK_ENV=development
+         > flask run
+
+   .. group-tab:: Powershell
+
+      .. code-block:: text
+
+         > $env:FLASK_ENV = "development"
+         > flask run
+
 See also:
 
 -   :doc:`/server` and :doc:`/cli` for information about running in

docs/server.rst

@@ -23,12 +23,32 @@ development server. It requires setting the ``FLASK_APP`` environment
 variable to point to your application, and ``FLASK_ENV=development`` to
 fully enable development mode.
 
-.. code-block:: text
+.. tabs::
+
+   .. group-tab:: Bash
+
+      .. code-block:: text
 
          $ export FLASK_APP=hello
          $ export FLASK_ENV=development
          $ flask run
 
+   .. group-tab:: CMD
+
+      .. code-block:: text
+
+         > set FLASK_APP=hello
+         > set FLASK_ENV=development
+         > flask run
+
+   .. group-tab:: Powershell
+
+      .. code-block:: text
+
+         > $env:FLASK_APP = "hello"
+         > $env:FLASK_ENV = "development"
+         > flask run
+
 This enables the development environment, including the interactive
 debugger and reloader, and then starts the server on
 http://localhost:5000/. Use ``flask run --help`` to see the available

docs/tutorial/deploy.rst

@@ -48,11 +48,29 @@ Pip will install your project along with its dependencies.
 Since this is a different machine, you need to run ``init-db`` again to
 create the database in the instance folder.
 
-.. code-block:: none
+.. tabs::
+
+   .. group-tab:: Bash
+
+      .. code-block:: text
 
          $ export FLASK_APP=flaskr
          $ flask init-db
 
+   .. group-tab:: CMD
+
+      .. code-block:: text
+
+         > set FLASK_APP=flaskr
+         > flask init-db
+
+   .. group-tab:: Powershell
+
+      .. code-block:: text
+
+         > $env:FLASK_APP = "flaskr"
+         > flask init-db
+
 When Flask detects that it's installed (not in editable mode), it uses
 a different directory for the instance folder. You can find it at
 ``venv/var/flaskr-instance`` instead.

docs/tutorial/factory.rst

@@ -135,25 +135,27 @@ exception, and restarts the server whenever you make changes to the
 code. You can leave it running and just reload the browser page as you
 follow the tutorial.
 
-For Linux and Mac:
+.. tabs::
 
-.. code-block:: none
+   .. group-tab:: Bash
+
+      .. code-block:: text
 
          $ export FLASK_APP=flaskr
          $ export FLASK_ENV=development
          $ flask run
 
-For Windows cmd, use ``set`` instead of ``export``:
+   .. group-tab:: CMD
 
-.. code-block:: none
+      .. code-block:: text
 
          > set FLASK_APP=flaskr
          > set FLASK_ENV=development
          > flask run
 
-For Windows PowerShell, use ``$env:`` instead of ``export``:
+   .. group-tab:: Powershell
 
-.. code-block:: none
+      .. code-block:: text
 
          > $env:FLASK_APP = "flaskr"
          > $env:FLASK_ENV = "development"

requirements/docs.in

@@ -3,3 +3,4 @@ packaging
 Sphinx
 sphinx-issues
 sphinxcontrib-log-cabinet
+sphinx-tabs

requirements/docs.txt

@@ -8,9 +8,11 @@ alabaster==0.7.12         # via sphinx
 babel==2.8.0              # via sphinx
 certifi==2020.4.5.1       # via requests
 chardet==3.0.4            # via requests
+colorama==0.4.3           # via sphinx
 docutils==0.16            # via sphinx
 idna==2.9                 # via requests
 imagesize==1.2.0          # via sphinx
+importlib-metadata==1.7.0  # via pallets-sphinx-themes
 jinja2==2.11.2            # via sphinx
 markupsafe==1.1.1         # via jinja2
 packaging==20.4           # via -r requirements/docs.in, pallets-sphinx-themes, sphinx
@@ -22,7 +24,8 @@ requests==2.23.0          # via sphinx
 six==1.15.0               # via packaging
 snowballstemmer==2.0.0    # via sphinx
 sphinx-issues==1.2.0      # via -r requirements/docs.in
-sphinx==3.2.1             # via -r requirements/docs.in, pallets-sphinx-themes, sphinx-issues, sphinxcontrib-log-cabinet
+sphinx-tabs==1.1.13       # via -r requirements/docs.in
+sphinx==3.2.1             # via -r requirements/docs.in, pallets-sphinx-themes, sphinx-issues, sphinx-tabs, sphinxcontrib-log-cabinet
 sphinxcontrib-applehelp==1.0.2  # via sphinx
 sphinxcontrib-devhelp==1.0.2  # via sphinx
 sphinxcontrib-htmlhelp==1.0.3  # via sphinx
@@ -31,6 +34,7 @@ sphinxcontrib-log-cabinet==1.0.1  # via -r requirements/docs.in
 sphinxcontrib-qthelp==1.0.3  # via sphinx
 sphinxcontrib-serializinghtml==1.1.4  # via sphinx
 urllib3==1.25.9           # via requests
+zipp==3.1.0               # via importlib-metadata
 
 # The following packages are considered to be unsafe in a requirements file:
 # setuptools