diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index c6d9327f..3da7e5cd 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -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. diff --git a/docs/cli.rst b/docs/cli.rst index abcfb7c6..b390c96e 100644 --- a/docs/cli.rst +++ b/docs/cli.rst @@ -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 diff --git a/docs/conf.py b/docs/conf.py index c9d3690a..796a31ee 100644 --- a/docs/conf.py +++ b/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), diff --git a/docs/config.rst b/docs/config.rst index f09518d4..70800c94 100644 --- a/docs/config.rst +++ b/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`: - $ 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 diff --git a/docs/debugging.rst b/docs/debugging.rst index 8370d624..a9f984b4 100644 --- a/docs/debugging.rst +++ b/docs/debugging.rst @@ -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: diff --git a/docs/installation.rst b/docs/installation.rst index e02e111e..aef7df0c 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -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. diff --git a/docs/patterns/appfactories.rst b/docs/patterns/appfactories.rst index 7ac4e110..79c78d60 100644 --- a/docs/patterns/appfactories.rst +++ b/docs/patterns/appfactories.rst @@ -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. diff --git a/docs/patterns/packages.rst b/docs/patterns/packages.rst index ab4db424..640f33a8 100644 --- a/docs/patterns/packages.rst +++ b/docs/patterns/packages.rst @@ -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:: diff --git a/docs/quickstart.rst b/docs/quickstart.rst index 7a0e8cea..c4a134a7 100644 --- a/docs/quickstart.rst +++ b/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:: - $ 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: diff --git a/docs/server.rst b/docs/server.rst index 980f3cf7..71704e4a 100644 --- a/docs/server.rst +++ b/docs/server.rst @@ -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 diff --git a/docs/tutorial/deploy.rst b/docs/tutorial/deploy.rst index 8c1713be..a5491dd8 100644 --- a/docs/tutorial/deploy.rst +++ b/docs/tutorial/deploy.rst @@ -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 diff --git a/docs/tutorial/factory.rst b/docs/tutorial/factory.rst index fbe1c8e2..ade5d40b 100644 --- a/docs/tutorial/factory.rst +++ b/docs/tutorial/factory.rst @@ -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: diff --git a/requirements/docs.in b/requirements/docs.in index 04942a0d..47aca27a 100644 --- a/requirements/docs.in +++ b/requirements/docs.in @@ -3,3 +3,4 @@ packaging Sphinx sphinx-issues sphinxcontrib-log-cabinet +sphinx-tabs diff --git a/requirements/docs.txt b/requirements/docs.txt index 8dc42451..a7899841 100644 --- a/requirements/docs.txt +++ b/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