From 02694d609f7ae43e023872a2f20b835590e10c0a Mon Sep 17 00:00:00 2001 From: defuz Date: Wed, 5 Nov 2014 07:03:55 +0300 Subject: [PATCH] docs: :command:`pip`, :option:`--debug` --- CHANGES | 2 +- docs/cli.rst | 20 ++++++++++---------- docs/extensions.rst | 2 +- docs/installation.rst | 18 +++++++++--------- docs/patterns/appfactories.rst | 4 ++-- docs/patterns/celery.rst | 2 +- docs/patterns/distribute.rst | 6 +++--- docs/quickstart.rst | 16 ++++++++-------- docs/server.rst | 10 +++++----- docs/tutorial/dbinit.rst | 6 +++--- docs/tutorial/setup.rst | 2 +- docs/upgrading.rst | 4 ++-- flask/app.py | 4 ++-- flask/cli.py | 4 ++-- 14 files changed, 50 insertions(+), 50 deletions(-) diff --git a/CHANGES b/CHANGES index 8fdf56cf..ac90e9b8 100644 --- a/CHANGES +++ b/CHANGES @@ -28,7 +28,7 @@ Version 1.0 - Added a workaround for a limitation in Python 3.3's namespace loader. - Added support for explicit root paths when using Python 3.3's namespace packages. -- Added ``flask`` and the ``flask.cli`` module to start the local +- Added :command:`flask` and the ``flask.cli`` module to start the local debug server through the click CLI system. This is recommended over the old ``flask.run()`` method as it works faster and more reliable due to a different design and also replaces ``Flask-Script``. diff --git a/docs/cli.rst b/docs/cli.rst index 4b7c051a..7faf208d 100644 --- a/docs/cli.rst +++ b/docs/cli.rst @@ -15,7 +15,7 @@ applications. Basic Usage ----------- -After installation of Flask you will now find a ``flask`` script installed +After installation of Flask you will now find a :command:`flask` script installed into your virtualenv. If you don't want to install Flask or you have a special use-case you can also use ``python -m flask`` to accomplish exactly the same. @@ -25,9 +25,9 @@ your Flask application's :attr:`Flask.cli` instance as well as some built-in commands that are always there. Flask extensions can also register more commands there if they desire so. -For the ``flask`` script to work, an application needs to be discovered. +For the :command:`flask` script to work, an application needs to be discovered. The two most common ways are either an environment variable -(``FLASK_APP``) or the ``--app`` / ``-a`` parameter. It should be the +(``FLASK_APP``) or the :option:`--app` / :option:`-a` parameter. It should be the import path for your application or the path to a Python file. In the latter case Flask will attempt to setup the Python path for you automatically and discover the module name but that might not always work. @@ -62,7 +62,7 @@ automatically also activate the correct application name. Debug Flag ---------- -The ``flask`` script can be run with ``--debug`` or ``--no-debug`` to +The :command:`flask` script can be run with :option:`--debug` or :option:`--no-debug` to automatically flip the debug flag of the application. This can also be configured by setting ``FLASK_DEBUG`` to ``1`` or ``0``. @@ -122,7 +122,7 @@ Factory Functions ----------------- In case you are using factory functions to create your application (see -:ref:`app-factories`) you will discover that the ``flask`` command cannot +:ref:`app-factories`) you will discover that the :command:`flask` command cannot work with them directly. Flask won't be able to figure out how to instantiate your application properly by itself. Because of this reason the recommendation is to create a separate file that instantiates @@ -145,14 +145,14 @@ it up:: export YOURAPPLICATION_CONFIG=/path/to/config.cfg export FLASK_APP=/path/to/autoapp.py -From this point onwards ``flask`` will find your application. +From this point onwards :command:`flask` will find your application. .. _custom-scripts: Custom Scripts -------------- -While the most common way is to use the ``flask`` command, you can also +While the most common way is to use the :command:`flask` command, you can also make your own "driver scripts". Since Flask uses click for the scripts there is no reason you cannot hook these scripts into any click application. There is one big caveat and that is, that commands @@ -162,7 +162,7 @@ necessary so that the commands know which Flask application they have to work with. To understand why you might want custom scripts you need to understand how -click finds and executes the Flask application. If you use the ``flask`` +click finds and executes the Flask application. If you use the :command:`flask` script you specify the application to work with on the command line or environment variable as an import name. This is simple but it has some limitations. Primarily it does not work with application factory @@ -223,7 +223,7 @@ step. call that function with the script info and ask for it to be created. 4. In step 2 you could see that the config is passed to the actual creation function. This config comes from the :func:`script_info_option` - decorator for the main script. It accepts a ``--config`` option and + decorator for the main script. It accepts a :option:`--config` option and then stores it in the script info so we can use it to create the application. 5. All is rounded up by invoking the script. @@ -239,7 +239,7 @@ both provide custom commands to click as well as not loading your application unless it has to. The reason for this is added flexibility. This way an application can provide custom commands, but even in the -absence of an application the ``flask`` script is still operational on a +absence of an application the :command:`flask` script is still operational on a basic level. In addition to that it means that the individual commands have the option to avoid creating an instance of the Flask application unless required. This is very useful as it allows the server commands for diff --git a/docs/extensions.rst b/docs/extensions.rst index b2524438..3d24574d 100644 --- a/docs/extensions.rst +++ b/docs/extensions.rst @@ -8,7 +8,7 @@ Finding Extensions ------------------ Flask extensions are listed on the `Flask Extension Registry`_ and can be -downloaded with ``easy_install`` or ``pip``. If you add a Flask extension +downloaded with :command:`easy_install` or :command:`pip`. If you add a Flask extension as dependency to your :file:`requirements.txt` or :file:`setup.py` file they are usually installed with a simple command or when your application installs. diff --git a/docs/installation.rst b/docs/installation.rst index 104706a4..bd4561b0 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -54,13 +54,13 @@ in your package manager. If you use Ubuntu, try:: $ sudo apt-get install python-virtualenv -If you are on Windows and don't have the `easy_install` command, you must +If you are on Windows and don't have the :command:`easy_install` command, you must install it first. Check the :ref:`windows-easy-install` section for more information about how to do that. Once you have it installed, run the same -commands as above, but without the `sudo` prefix. +commands as above, but without the :command:`sudo` prefix. Once you have virtualenv installed, just fire up a shell and create -your own environment. I usually create a project folder and a `venv` +your own environment. I usually create a project folder and a :file:`venv` folder within:: $ mkdir myproject @@ -99,19 +99,19 @@ System-Wide Installation ------------------------ This is possible as well, though I do not recommend it. Just run -`pip` with root privileges:: +:command:`pip` with root privileges:: $ sudo pip install Flask (On Windows systems, run it in a command-prompt window with administrator -privileges, and leave out `sudo`.) +privileges, and leave out :command:`sudo`.) Living on the Edge ------------------ If you want to work with the latest version of Flask, there are two ways: you -can either let `pip` pull in the development version, or you can tell +can either let :command:`pip` pull in the development version, or you can tell it to operate on a git checkout. Either way, virtualenv is recommended. Get the git checkout in a new virtualenv and run in development mode:: @@ -157,14 +157,14 @@ you can upgrade them by running:: > pip install --upgrade pip setuptools -Most often, once you pull up a command prompt you want to be able to type ``pip`` -and ``python`` which will run those things, but this might not automatically happen +Most often, once you pull up a command prompt you want to be able to type :command:``pip`` +and :command:``python`` which will run those things, but this might not automatically happen on Windows, because it doesn't know where those executables are (give either a try!). To fix this, you should be able to navigate to your Python install directory (e.g ``C:\Python27``), then go to ``Tools``, then ``Scripts``; then find the ``win_add2path.py`` file and run that. Open a **new** Command Prompt and -check that you can now just type ``python`` to bring up the interpreter. +check that you can now just type :command:``python`` to bring up the interpreter. Finally, to install `virtualenv`_, you can simply run:: diff --git a/docs/patterns/appfactories.rst b/docs/patterns/appfactories.rst index 2ed7e4f7..87b9d46f 100644 --- a/docs/patterns/appfactories.rst +++ b/docs/patterns/appfactories.rst @@ -90,14 +90,14 @@ Using Applications ------------------ So to use such an application you then have to create the application -first in a separate file otherwise the ``flask`` command won't be able +first in a separate file otherwise the :command:`flask` command won't be able to find it. Here an example :file:`exampleapp.py` file that creates such an application:: from yourapplication import create_app app = create_app('/path/to/config.cfg') -It can then be used with the ``flask`` command:: +It can then be used with the :command:`flask` command:: flask --app=exampleapp run diff --git a/docs/patterns/celery.rst b/docs/patterns/celery.rst index aa729b2f..c1d56472 100644 --- a/docs/patterns/celery.rst +++ b/docs/patterns/celery.rst @@ -13,7 +13,7 @@ Installing Celery ----------------- Celery is on the Python Package Index (PyPI), so it can be installed with -standard Python tools like ``pip`` or ``easy_install``:: +standard Python tools like :command:`pip` or :command:`easy_install`:: $ pip install celery diff --git a/docs/patterns/distribute.rst b/docs/patterns/distribute.rst index 402e88d1..b168f148 100644 --- a/docs/patterns/distribute.rst +++ b/docs/patterns/distribute.rst @@ -18,9 +18,9 @@ make larger applications easier to distribute: this system is the entry point support which allows one package to declare an "entry point" another package can hook into to extend the other package. -- **installation manager**: `easy_install`, which comes with distribute - can install other libraries for you. You can also use `pip`_ which - sooner or later will replace `easy_install` which does more than just +- **installation manager**: :command:`easy_install`, which comes with distribute + can install other libraries for you. You can also use :command:`pip`_ which + sooner or later will replace :command:`easy_install` which does more than just installing packages for you. Flask itself, and all the libraries you can find on the cheeseshop diff --git a/docs/quickstart.rst b/docs/quickstart.rst index 8acb0e97..f045c3ac 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -24,8 +24,8 @@ Just save it as :file:`hello.py` (or something similar) and run it with your Pyt interpreter. Make sure to not call your application :file:`flask.py` because this would conflict with Flask itself. -To run the application you can either use the ``flask`` command or -python's ``-m`` switch with Flask:: +To run the application you can either use the :command:`flask` command or +python's :option:`-m` switch with Flask:: $ flask -a hello run * Running on http://127.0.0.1:5000/ @@ -79,7 +79,7 @@ To stop the server, hit control-C. What to do if the Server does not Start --------------------------------------- -In case the ``python -m flask`` fails or ``flask`` does not exist, +In case the ``python -m flask`` fails or :command:`flask` does not exist, there are multiple reasons this might be the case. First of all you need to look at the error message. @@ -87,7 +87,7 @@ Old Version of Flask ```````````````````` Versions of Flask older than 1.0 use to have different ways to start the -application. In short, the ``flask`` command did not exist, and +application. In short, the :command:`flask` command did not exist, and neither did ``python -m flask``. In that case you have two options: either upgrade to newer Flask versions or have a look at the :ref:`server` docs to see the alternative method for running a server. @@ -96,7 +96,7 @@ Python older 2.7 ```````````````` In case you have a version of Python older than 2.7 ``python -m flask`` -does not work. You can either use ``flask`` or ``python -m +does not work. You can either use :command:`flask` or ``python -m flask.cli`` as an alternative. This is because Python before 2.7 does no permit packages to act as executable modules. For more information see :ref:`cli`. @@ -104,7 +104,7 @@ permit packages to act as executable modules. For more information see Invalid Import Name ``````````````````` -The ``-a`` argument to ``flask`` is the name of the module to import. In +The :option:`-a` argument to :command:`flask` is the name of the module to import. In case that module is incorrectly named you will get an import error upon start (or if debug is enabled when you navigate to the application). It will tell you what it tried to import and why it failed. @@ -117,14 +117,14 @@ The most common reason is a typo or because you did not actually create an Debug Mode ---------- -The ``flask`` script is nice to start a local development server, but +The :command:`flask` script is nice to start a local development server, but you would have to restart it manually after each change to your code. That is not very nice and Flask can do better. If you enable debug support the server will reload itself on code changes, and it will also provide you with a helpful debugger if things go wrong. There are different ways to enable the debug mode. The most obvious one -is the ``--debug`` parameter to the ``flask`` command:: +is the :option:`--debug` parameter to the :command:`flask` command:: flask --debug -a hello run diff --git a/docs/server.rst b/docs/server.rst index 02887f80..3614ff80 100644 --- a/docs/server.rst +++ b/docs/server.rst @@ -6,19 +6,19 @@ Development Server .. currentmodule:: flask Starting with Flask 1.0 there are multiple built-in ways to run a -development server. The best one is the ``flask`` command line utility +development server. The best one is the :command:`flask` command line utility but you can also continue using the :meth:`Flask.run` method. Command Line ------------ -The ``flask`` command line script (:ref:`cli`) is strongly recommende for +The :command:`flask` command line script (:ref:`cli`) is strongly recommende for development because it provides a superior reload experience due to how it loads the application. The basic usage is like this:: $ flask -a my_application --debug run -This will enable the debugger, the reloader and then start the server on +This will enable the debugger, the reloader and then start the server on *http://localhost:5000/*. The individual features of the server can be controlled by passing more @@ -32,7 +32,7 @@ In Code The alternative way to start the application is through the :meth:`Flask.run` method. This will immediately launch a local server -exactly the same way the ``flask`` script does. +exactly the same way the :command:`flask` script does. Example:: @@ -40,7 +40,7 @@ Example:: app.run() This works well for the common case but it does not work well for -development which is why from Flask 1.0 onwards the ``flask`` method is +development which is why from Flask 1.0 onwards the :command:`flask` method is recommended. The reason for this is that due to how the reload mechanism works there are some bizarre side-effects (like executing certain code twice, sometimes crashing without message or dying when a syntax or diff --git a/docs/tutorial/dbinit.rst b/docs/tutorial/dbinit.rst index 43febd74..d8fc8569 100644 --- a/docs/tutorial/dbinit.rst +++ b/docs/tutorial/dbinit.rst @@ -20,7 +20,7 @@ requires that we provide the path to the database which can introduce errors. It's a good idea to add a function that initializes the database for you to the application. -To do this we can create a function and hook it into the ``flask`` command +To do this we can create a function and hook it into the :command:`flask` command that initializes the database. Let me show you the code first. Just add this function below the `connect_db` function in :file:`flaskr.py`:: @@ -37,7 +37,7 @@ this function below the `connect_db` function in :file:`flaskr.py`:: print 'Initialized the database.' The ``app.cli.command()`` decorator registers a new command with the -``flask`` script. When the command executes Flask will automatically +:command:`flask` script. When the command executes Flask will automatically create a application context for us bound to the right application. Within the function we can then access :attr:`flask.g` and other things as we would expect. When the script ends, the application context tears down @@ -58,7 +58,7 @@ On that cursor there is a method to execute a complete script. Finally we only have to commit the changes. SQLite 3 and other transactional databases will not commit unless you explicitly tell it to. -Now it is possible to create a database with the ``flask`` script:: +Now it is possible to create a database with the :command:`flask` script:: flask --app=flaskr initdb Initialized the database. diff --git a/docs/tutorial/setup.rst b/docs/tutorial/setup.rst index 6180a5e2..faf96817 100644 --- a/docs/tutorial/setup.rst +++ b/docs/tutorial/setup.rst @@ -93,7 +93,7 @@ without problems. Do this with the following command:: flask --app=flaskr --debug run -The ``--debug`` flag enables or disables the interactive debugger. *Never +The :option:`--debug` flag enables or disables the interactive debugger. *Never leave debug mode activated in a production system*, because it will allow users to execute code on the server! diff --git a/docs/upgrading.rst b/docs/upgrading.rst index 0a83dd9f..2ec501a2 100644 --- a/docs/upgrading.rst +++ b/docs/upgrading.rst @@ -14,8 +14,8 @@ This section of the documentation enumerates all the changes in Flask from release to release and how you can change your code to have a painless updating experience. -If you want to use the `easy_install` command to upgrade your Flask -installation, make sure to pass it the ``-U`` parameter:: +If you want to use the :command:`easy_install` command to upgrade your Flask +installation, make sure to pass it the :option:`-U` parameter:: $ easy_install -U Flask diff --git a/flask/app.py b/flask/app.py index f6ca4e83..ba5ec385 100644 --- a/flask/app.py +++ b/flask/app.py @@ -523,7 +523,7 @@ class Flask(_PackageBoundObject): view_func=self.send_static_file) #: The click command line context for this application. Commands - #: registered here show up in the ``flask`` command once the + #: registered here show up in the :command:`flask` command once the #: application has been discovered. The default commands are #: provided by Flask itself and can be overridden. #: @@ -773,7 +773,7 @@ class Flask(_PackageBoundObject): It is not recommended to use this function for development with automatic reloading as this is badly supported. Instead you should - be using the ``flask`` command line script's ``runserver`` + be using the :command:`flask` command line script's ``runserver`` support. .. admonition:: Keep in Mind diff --git a/flask/cli.py b/flask/cli.py index 47c0406a..547d81a5 100644 --- a/flask/cli.py +++ b/flask/cli.py @@ -267,10 +267,10 @@ class FlaskGroup(AppGroup): :param add_default_commands: if this is True then the default run and shell commands wil be added. - :param add_app_option: adds the default ``--app`` option. This gets + :param add_app_option: adds the default :option:`--app` option. This gets automatically disabled if a `create_app` callback is defined. - :param add_debug_option: adds the default ``--debug`` option. + :param add_debug_option: adds the default :option:`--debug` option. :param create_app: an optional callback that is passed the script info and returns the loaded app. """