docs: :command:pip, :option:--debug

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``.

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

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.
 

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

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
 

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
 

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

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
 

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

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.

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!
 

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
 

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

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.
     """