maya-chen/flask
1
0
Fork 0
forked from orbit-oss/flask
Code Pull requests Activity

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

Browse source 
* Enable Sphinx extension sphinx-tabs

* Add command tabs for all export commands

* Add command tabs for all venv commands

Fix trim spaces
This commit is contained in:
Grey Li 2020-10-16 05:08:37 +08:00 • committed by GitHub
parent c5a5d9b30b
commit 1035efc7d6
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
14 changed files with 498 additions and 126 deletions
Download patch file Download diff file Expand all files Collapse all files

17
CONTRIBUTING.rst
View file

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

189
docs/cli.rst
View file

@ -18,20 +18,28 @@ 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::
$ export FLASK_APP=hello
$ flask run
.. group-tab:: Bash
Windows CMD::
.. code-block:: text
> set FLASK_APP=hello
> flask run
$ export FLASK_APP=hello
$ flask run
Windows PowerShell::
.. group-tab:: CMD
> $env:FLASK_APP = "hello"
> flask run
.. code-block:: text
> set FLASK_APP=hello
> flask run
.. group-tab:: Powershell
.. code-block:: text
> $env:FLASK_APP = "hello"
> flask run
While ``FLASK_APP`` supports a variety of options for specifying your
application, most use cases should be simple. Here are the typical values:
@ -128,16 +136,49 @@ 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
* 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:: 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
* 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
Watch Extra Files with the Reloader
@ -149,14 +190,40 @@ 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::
$ flask run --extra-files file1:dirA/file2:dirB/
# or
$ export 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:: Bash
.. code-block:: text
$ flask run --extra-files file1:dirA/file2:dirB/
# or
$ export 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:: 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,11 +273,31 @@ 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::
$ export FLASK_RUN_PORT=8000
$ flask run
* Running on http://127.0.0.1:8000/
.. 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,10 +321,28 @@ 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::
$ export FLASK_SKIP_DOTENV=1
$ flask run
.. 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,13 +352,25 @@ 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::
$ export FLASK_APP=hello
.. group-tab:: Bash
Windows CMD, :file:`venv\\Scripts\\activate.bat`::
Unix Bash, :file:`venv/bin/activate`::
> set FLASK_APP=hello
$ export FLASK_APP=hello
.. 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

1
docs/conf.py
View file

@ -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),

95
docs/config.rst
View file

@ -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`:
$ export FLASK_ENV=development
$ flask run
.. tabs::
(On Windows, use ``set`` instead of ``export``.)
.. 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
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
Linux or OS X with the export command in the shell before starting the
server::
environment variable points to. This environment variable can be set
in the shell before starting the server:
$ export YOURAPPLICATION_SETTINGS=/path/to/settings.cfg
$ python run-app.py
* Running on http://127.0.0.1:5000/
* Restarting with reloader...
.. tabs::
On Windows systems use the `set` builtin instead::
.. group-tab:: Bash
> set YOURAPPLICATION_SETTINGS=\path\to\settings.cfg
.. code-block:: text
$ export YOURAPPLICATION_SETTINGS=/path/to/settings.cfg
$ flask run
* Running on http://127.0.0.1:5000/
.. 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
the shell before starting the server::
Environment variables can be set in the shell before starting the server:
$ export SECRET_KEY='5f352379324c22463451387a0aec5d2f'
$ export MAIL_ENABLED=false
$ python run-app.py
* Running on http://127.0.0.1:5000/
.. tabs::
On Windows systems use the ``set`` builtin instead::
.. group-tab:: Bash
> set SECRET_KEY='5f352379324c22463451387a0aec5d2f'
.. code-block:: text
$ export SECRET_KEY="5f352379324c22463451387a0aec5d2f"
$ export MAIL_ENABLED=false
$ flask run
* Running on http://127.0.0.1:5000/
.. group-tab:: CMD
.. 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

48
docs/debugging.rst
View file

@ -44,10 +44,28 @@ 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::
$ export FLASK_ENV=development
$ flask run
.. 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
@ -79,10 +97,28 @@ which can interfere.
When running from the command line:
.. code-block:: text
.. tabs::
$ export FLASK_ENV=development
$ flask run --no-debugger --no-reload
.. 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:

34
docs/installation.rst
View file

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

52
docs/patterns/appfactories.rst
View file

@ -87,16 +87,56 @@ 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:
$ export FLASK_APP=myapp
$ flask run
.. 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:
$ export FLASK_APP="myapp:create_app('dev')"
$ flask run
.. 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.

44
docs/patterns/packages.rst
View file

@ -57,15 +57,51 @@ 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:
$ export FLASK_APP=yourapplication
.. 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:
$ export FLASK_ENV=development
.. 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::

53
docs/quickstart.rst
View file

@ -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::
$ export FLASK_APP=hello.py
$ flask run
* Running on http://127.0.0.1:5000/
.. group-tab:: Bash
If you are on Windows, the environment variable syntax depends on command line
interpreter. On Command Prompt::
.. code-block:: text
C:\path\to\app>set FLASK_APP=hello.py
$ export FLASK_APP=hello.py
$ flask run
* Running on http://127.0.0.1:5000/
And on PowerShell::
.. group-tab:: CMD
PS C:\path\to\app> $env:FLASK_APP = "hello.py"
.. code-block:: text
> set FLASK_APP=hello.py
> flask run
* Running on http://127.0.0.1:5000/
.. 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,10 +146,28 @@ 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::
$ export FLASK_ENV=development
$ flask run
.. 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:

28
docs/server.rst
View file

@ -23,11 +23,31 @@ 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::
$ export FLASK_APP=hello
$ export FLASK_ENV=development
$ flask run
.. 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

24
docs/tutorial/deploy.rst
View file

@ -48,10 +48,28 @@ 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::
$ export FLASK_APP=flaskr
$ flask init-db
.. 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

32
docs/tutorial/factory.rst
View file

@ -135,29 +135,31 @@ 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
$ export FLASK_APP=flaskr
$ export FLASK_ENV=development
$ flask run
.. code-block:: text
For Windows cmd, use ``set`` instead of ``export``:
$ export FLASK_APP=flaskr
$ export FLASK_ENV=development
$ flask run
.. code-block:: none
.. group-tab:: CMD
> set FLASK_APP=flaskr
> set FLASK_ENV=development
> flask run
.. code-block:: text
For Windows PowerShell, use ``$env:`` instead of ``export``:
> set FLASK_APP=flaskr
> set FLASK_ENV=development
> flask run
.. code-block:: none
.. group-tab:: Powershell
> $env:FLASK_APP = "flaskr"
> $env:FLASK_ENV = "development"
> flask run
.. code-block:: text
> $env:FLASK_APP = "flaskr"
> $env:FLASK_ENV = "development"
> flask run
You'll see output similar to this:

1
requirements/docs.in
View file

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

6
requirements/docs.txt
View file

@ -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