From 171aabc87dd8bff0367d0555c8be6105b00c22ce Mon Sep 17 00:00:00 2001 From: David Lord Date: Sat, 4 Apr 2020 12:57:14 -0700 Subject: [PATCH] remove unused ref directives replace page refs with doc directives --- docs/advanced_foreword.rst | 2 -- docs/api.rst | 12 +++------ docs/appcontext.rst | 2 -- docs/becomingbig.rst | 10 +++---- docs/blueprints.rst | 9 +++---- docs/changelog.rst | 4 +-- docs/cli.rst | 4 +-- docs/config.rst | 8 +++--- docs/deploying/fastcgi.rst | 2 -- docs/deploying/index.rst | 2 -- docs/deploying/mod_wsgi.rst | 2 -- docs/deploying/uwsgi.rst | 2 -- docs/deploying/wsgi-standalone.rst | 2 -- docs/design.rst | 6 ++--- docs/errorhandling.rst | 5 +--- docs/extensiondev.rst | 11 ++++---- docs/extensions.rst | 2 -- docs/foreword.rst | 7 ++--- docs/index.rst | 13 +++++---- docs/installation.rst | 6 ++--- docs/license.rst | 6 ++--- docs/patterns/appdispatch.rst | 22 +++++++--------- docs/patterns/appfactories.rst | 4 +-- docs/patterns/caching.rst | 2 -- docs/patterns/deferredcallbacks.rst | 2 -- docs/patterns/distribute.rst | 15 +++++------ docs/patterns/errorpages.rst | 6 ++--- docs/patterns/fabric.rst | 12 ++++----- docs/patterns/fileuploads.rst | 4 +-- docs/patterns/flashing.rst | 2 -- docs/patterns/index.rst | 2 -- docs/patterns/mongokit.rst | 7 ----- docs/patterns/packages.rst | 14 ++++------ docs/patterns/sqlalchemy.rst | 9 +++---- docs/patterns/sqlite3.rst | 3 --- docs/patterns/templateinheritance.rst | 2 -- docs/patterns/viewdecorators.rst | 6 ++--- docs/patterns/wtforms.rst | 4 +-- docs/quickstart.rst | 38 +++++++++++++-------------- docs/reqcontext.rst | 4 +-- docs/security.rst | 4 +-- docs/shell.rst | 6 ++--- docs/signals.rst | 4 +-- docs/templating.rst | 4 +-- docs/testing.rst | 8 +++--- docs/tutorial/database.rst | 8 +++--- docs/tutorial/index.rst | 8 +++--- docs/tutorial/next.rst | 4 +-- docs/views.rst | 2 -- src/flask/app.py | 4 +-- src/flask/blueprints.py | 2 +- src/flask/cli.py | 4 +-- src/flask/helpers.py | 10 +++---- src/flask/json/__init__.py | 5 ++-- src/flask/testing.py | 2 +- 55 files changed, 129 insertions(+), 221 deletions(-) delete mode 100644 docs/patterns/mongokit.rst diff --git a/docs/advanced_foreword.rst b/docs/advanced_foreword.rst index 4ac81905..9c36158a 100644 --- a/docs/advanced_foreword.rst +++ b/docs/advanced_foreword.rst @@ -1,5 +1,3 @@ -.. _advanced_foreword: - Foreword for Experienced Programmers ==================================== diff --git a/docs/api.rst b/docs/api.rst index ec8ba9dc..801a65bd 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -1,5 +1,3 @@ -.. _api: - API === @@ -326,12 +324,12 @@ happens automatically (but it's harmless to include ``|safe`` anyway). .. admonition:: Auto-Sort JSON Keys - The configuration variable ``JSON_SORT_KEYS`` (:ref:`config`) can be - set to false to stop Flask from auto-sorting keys. By default sorting + The configuration variable :data:`JSON_SORT_KEYS` can be set to + ``False`` to stop Flask from auto-sorting keys. By default sorting is enabled and outside of the app context sorting is turned on. - Notice that disabling key sorting can cause issues when using content - based HTTP caches and Python's hash randomization feature. + Notice that disabling key sorting can cause issues when using + content based HTTP caches and Python's hash randomization feature. .. autofunction:: jsonify @@ -634,7 +632,6 @@ The following signals exist in Flask: .. _blinker: https://pypi.org/project/blinker/ -.. _class-based-views: Class-Based Views ----------------- @@ -761,7 +758,6 @@ instead of the `view_func` parameter. handling. They have to be specified as keyword arguments. =============== ========================================================== -.. _view-func-options: View Function Options --------------------- diff --git a/docs/appcontext.rst b/docs/appcontext.rst index 53c5ad36..e5e326fd 100644 --- a/docs/appcontext.rst +++ b/docs/appcontext.rst @@ -1,7 +1,5 @@ .. currentmodule:: flask -.. _app-context: - The Application Context ======================= diff --git a/docs/becomingbig.rst b/docs/becomingbig.rst index 1e05fdce..5e7a88e0 100644 --- a/docs/becomingbig.rst +++ b/docs/becomingbig.rst @@ -1,5 +1,3 @@ -.. _becomingbig: - Becoming Big ============ @@ -20,8 +18,8 @@ project. Hook. Extend. ------------- -The :ref:`api` docs are full of available overrides, hook points, and -:ref:`signals`. You can provide custom classes for things like the +The :doc:`/api` docs are full of available overrides, hook points, and +:doc:`/signals`. You can provide custom classes for things like the request and response objects. Dig deeper on the APIs you use, and look for the customizations which are available out of the box in a Flask release. Look for ways in which your project can be refactored into a @@ -35,13 +33,13 @@ Subclass. The :class:`~flask.Flask` class has many methods designed for subclassing. You can quickly add or customize behavior by subclassing :class:`~flask.Flask` (see the linked method docs) and using that subclass wherever you instantiate an -application class. This works well with :ref:`app-factories`. +application class. This works well with :doc:`/patterns/appfactories`. See :doc:`/patterns/subclassing` for an example. Wrap with middleware. --------------------- -The :ref:`app-dispatch` chapter shows in detail how to apply middleware. You +The :doc:`/patterns/appdispatch` pattern shows in detail how to apply middleware. You can introduce WSGI middleware to wrap your Flask instances and introduce fixes and changes at the layer between your Flask application and your HTTP server. Werkzeug includes several `middlewares diff --git a/docs/blueprints.rst b/docs/blueprints.rst index f4454752..1f10a301 100644 --- a/docs/blueprints.rst +++ b/docs/blueprints.rst @@ -1,5 +1,3 @@ -.. _blueprints: - Modular Applications with Blueprints ==================================== @@ -37,8 +35,9 @@ Blueprints in Flask are intended for these cases: A blueprint in Flask is not a pluggable app because it is not actually an application -- it's a set of operations which can be registered on an application, even multiple times. Why not have multiple application -objects? You can do that (see :ref:`app-dispatch`), but your applications -will have separate configs and will be managed at the WSGI layer. +objects? You can do that (see :doc:`/patterns/appdispatch`), but your +applications will have separate configs and will be managed at the WSGI +layer. Blueprints instead provide separation at the Flask level, share application config, and can change an application object as necessary with @@ -274,4 +273,4 @@ at the application level using the ``request`` proxy object:: else: return ex -More information on error handling see :ref:`errorpages`. +More information on error handling see :doc:`/patterns/errorpages`. diff --git a/docs/changelog.rst b/docs/changelog.rst index 218fe333..955deaf2 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -1,4 +1,4 @@ -Changelog -========= +Changes +======= .. include:: ../CHANGES.rst diff --git a/docs/cli.rst b/docs/cli.rst index c50872a7..d99742a6 100644 --- a/docs/cli.rst +++ b/docs/cli.rst @@ -1,7 +1,5 @@ .. currentmodule:: flask -.. _cli: - Command Line Interface ====================== @@ -99,7 +97,7 @@ replaces the :meth:`Flask.run` method in most cases. :: .. warning:: Do not use this command to run your application in production. Only use the development server during development. The development server is provided for convenience, but is not designed to be particularly secure, - stable, or efficient. See :ref:`deployment` for how to run in production. + stable, or efficient. See :doc:`/deploying/index` for how to run in production. Open a Shell diff --git a/docs/config.rst b/docs/config.rst index d93fc366..891c299f 100644 --- a/docs/config.rst +++ b/docs/config.rst @@ -1,5 +1,3 @@ -.. _config: - Configuration Handling ====================== @@ -278,7 +276,7 @@ The following configuration values are used internally by Flask: Inform the application what path it is mounted under by the application / web server. This is used for generating URLs outside the context of a request (inside a request, the dispatcher is responsible for setting - ``SCRIPT_NAME`` instead; see :ref:`Application Dispatching ` + ``SCRIPT_NAME`` instead; see :doc:`/patterns/appdispatch` for examples of dispatch configuration). Will be used for the session cookie path if ``SESSION_COOKIE_PATH`` is not @@ -399,7 +397,7 @@ Configuring from Python Files Configuration becomes more useful if you can store it in a separate file, ideally located outside the actual application package. This makes packaging and distributing your application possible via various package -handling tools (:ref:`distribute-deployment`) and finally modifying the +handling tools (:doc:`/patterns/distribute`) and finally modifying the configuration file afterwards. So a common pattern is this:: @@ -628,7 +626,7 @@ your configuration files. However here a list of good recommendations: - Use a tool like `fabric`_ in production to push code and configurations separately to the production server(s). For some details about how to do that, head over to the - :ref:`fabric-deployment` pattern. + :doc:`/patterns/fabric` pattern. .. _fabric: https://www.fabfile.org/ diff --git a/docs/deploying/fastcgi.rst b/docs/deploying/fastcgi.rst index 33704062..ef2201c8 100644 --- a/docs/deploying/fastcgi.rst +++ b/docs/deploying/fastcgi.rst @@ -1,5 +1,3 @@ -.. _deploying-fastcgi: - FastCGI ======= diff --git a/docs/deploying/index.rst b/docs/deploying/index.rst index 01584d36..54380599 100644 --- a/docs/deploying/index.rst +++ b/docs/deploying/index.rst @@ -1,5 +1,3 @@ -.. _deployment: - Deployment Options ================== diff --git a/docs/deploying/mod_wsgi.rst b/docs/deploying/mod_wsgi.rst index d8f02e7c..1ac9080a 100644 --- a/docs/deploying/mod_wsgi.rst +++ b/docs/deploying/mod_wsgi.rst @@ -1,5 +1,3 @@ -.. _mod_wsgi-deployment: - mod_wsgi (Apache) ================= diff --git a/docs/deploying/uwsgi.rst b/docs/deploying/uwsgi.rst index cbbf00aa..22930d7b 100644 --- a/docs/deploying/uwsgi.rst +++ b/docs/deploying/uwsgi.rst @@ -1,5 +1,3 @@ -.. _deploying-uwsgi: - uWSGI ===== diff --git a/docs/deploying/wsgi-standalone.rst b/docs/deploying/wsgi-standalone.rst index 6614928b..1339a625 100644 --- a/docs/deploying/wsgi-standalone.rst +++ b/docs/deploying/wsgi-standalone.rst @@ -1,5 +1,3 @@ -.. _deploying-wsgi-standalone: - Standalone WSGI Containers ========================== diff --git a/docs/design.rst b/docs/design.rst index f67decbd..ae76c921 100644 --- a/docs/design.rst +++ b/docs/design.rst @@ -1,5 +1,3 @@ -.. _design: - Design Decisions in Flask ========================= @@ -77,7 +75,7 @@ to the application object :meth:`~flask.Flask.wsgi_app`). Furthermore this design makes it possible to use a factory function to create the application which is very helpful for unit testing and similar -things (:ref:`app-factories`). +things (:doc:`/patterns/appfactories`). The Routing System ------------------ @@ -169,7 +167,7 @@ large applications harder to maintain. However Flask is just not designed for large applications or asynchronous servers. Flask wants to make it quick and easy to write a traditional web application. -Also see the :ref:`becomingbig` section of the documentation for some +Also see the :doc:`/becomingbig` section of the documentation for some inspiration for larger applications based on Flask. diff --git a/docs/errorhandling.rst b/docs/errorhandling.rst index b565aa3e..b7b2edf1 100644 --- a/docs/errorhandling.rst +++ b/docs/errorhandling.rst @@ -1,5 +1,3 @@ -.. _application-errors: - Application Errors ================== @@ -68,7 +66,6 @@ Follow-up reads: * `Getting started with Sentry `_ * `Flask-specific documentation `_. -.. _error-handlers: Error handlers -------------- @@ -239,7 +236,7 @@ Debugging Application Errors ============================ For production applications, configure your application with logging and -notifications as described in :ref:`application-errors`. This section provides +notifications as described in :doc:`/logging`. This section provides pointers when debugging deployment configuration and digging deeper with a full-featured Python debugger. diff --git a/docs/extensiondev.rst b/docs/extensiondev.rst index 11d6684d..1f4be990 100644 --- a/docs/extensiondev.rst +++ b/docs/extensiondev.rst @@ -27,9 +27,10 @@ their :file:`setup.py` files. But what do extensions look like themselves? An extension has to ensure that it works with multiple Flask application instances at once. This is a requirement because many people will use patterns like the -:ref:`app-factories` pattern to create their application as needed to aid -unittests and to support multiple configurations. Because of that it is -crucial that your application supports that kind of behavior. +:doc:`/patterns/appfactories` pattern to create their application as +needed to aid unittests and to support multiple configurations. Because +of that it is crucial that your application supports that kind of +behavior. Most importantly the extension must be shipped with a :file:`setup.py` file and registered on PyPI. Also the development checkout link should work so @@ -117,8 +118,8 @@ Initializing Extensions Many extensions will need some kind of initialization step. For example, consider an application that's currently connecting to SQLite like the -documentation suggests (:ref:`sqlite3`). So how does the extension -know the name of the application object? +documentation suggests (:doc:`/patterns/sqlite3`). So how does the +extension know the name of the application object? Quite simple: you pass it to it. diff --git a/docs/extensions.rst b/docs/extensions.rst index 8ae20eaa..784fd807 100644 --- a/docs/extensions.rst +++ b/docs/extensions.rst @@ -1,5 +1,3 @@ -.. _extensions: - Extensions ========== diff --git a/docs/foreword.rst b/docs/foreword.rst index 37b4d109..6a6d17f9 100644 --- a/docs/foreword.rst +++ b/docs/foreword.rst @@ -49,8 +49,5 @@ the Python web interface. Flask includes many hooks to customize its behavior. Should you need more customization, the Flask class is built for subclassing. If you are interested -in that, check out the :ref:`becomingbig` chapter. If you are curious about -the Flask design principles, head over to the section about :ref:`design`. - -Continue to :ref:`installation`, the :ref:`quickstart`, or the -:ref:`advanced_foreword`. +in that, check out the :doc:`becomingbig` chapter. If you are curious about +the Flask design principles, head over to the section about :doc:`design`. diff --git a/docs/index.rst b/docs/index.rst index 5d9cb5ce..eef180d6 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,7 +1,5 @@ .. rst-class:: hide-header -.. rst-class:: hide-header - Welcome to Flask ================ @@ -10,12 +8,13 @@ Welcome to Flask :align: center :target: https://palletsprojects.com/p/flask/ -Welcome to Flask's documentation. Get started with :ref:`installation` -and then get an overview with the :ref:`quickstart`. There is also a -more detailed :ref:`tutorial` that shows how to create a small but +Welcome to Flask's documentation. Get started with :doc:`installation` +and then get an overview with the :doc:`quickstart`. There is also a +more detailed :doc:`tutorial/index` that shows how to create a small but complete application with Flask. Common patterns are described in the -:ref:`patterns` section. The rest of the docs describe each component of -Flask in detail, with a full reference in the :ref:`api` section. +:doc:`patterns/index` section. The rest of the docs describe each +component of Flask in detail, with a full reference in the :doc:`api` +section. Flask depends on the `Jinja`_ template engine and the `Werkzeug`_ WSGI toolkit. The documentation for these libraries can be found at: diff --git a/docs/installation.rst b/docs/installation.rst index 52add0ba..c99d82cf 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -1,5 +1,3 @@ -.. _installation: - Installation ============ @@ -40,7 +38,7 @@ Optional dependencies These distributions will not be installed automatically. Flask will detect and use them if you install them. -* `Blinker`_ provides support for :ref:`signals`. +* `Blinker`_ provides support for :doc:`signals`. * `SimpleJSON`_ is a fast JSON implementation that is compatible with Python's ``json`` module. It is preferred for JSON operations if it is installed. @@ -74,6 +72,8 @@ Python comes bundled with the :mod:`venv` module to create virtual environments. +.. _install-create-env: + Create an environment ~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/license.rst b/docs/license.rst index 24c42a91..7d0c2f39 100644 --- a/docs/license.rst +++ b/docs/license.rst @@ -4,9 +4,9 @@ License Source License -------------- -This license applies to all files in the Flask repository and source -distribution. This includes Flask's source code, the examples, and -tests, as well as the documentation. +The BSD-3-Clause license applies to all files in the Flask repository +and source distribution. This includes Flask's source code, the +examples, and tests, as well as the documentation. .. include:: ../LICENSE.rst diff --git a/docs/patterns/appdispatch.rst b/docs/patterns/appdispatch.rst index 89824951..0c5e846e 100644 --- a/docs/patterns/appdispatch.rst +++ b/docs/patterns/appdispatch.rst @@ -1,5 +1,3 @@ -.. _app-dispatch: - Application Dispatching ======================= @@ -10,25 +8,25 @@ Django and a Flask application in the same interpreter side by side if you want. The usefulness of this depends on how the applications work internally. -The fundamental difference from the :ref:`module approach -` is that in this case you are running the same or -different Flask applications that are entirely isolated from each other. -They run different configurations and are dispatched on the WSGI level. +The fundamental difference from :doc:`packages` is that in this case you +are running the same or different Flask applications that are entirely +isolated from each other. They run different configurations and are +dispatched on the WSGI level. Working with this Document -------------------------- -Each of the techniques and examples below results in an ``application`` object -that can be run with any WSGI server. For production, see :ref:`deployment`. -For development, Werkzeug provides a builtin server for development available -at :func:`werkzeug.serving.run_simple`:: +Each of the techniques and examples below results in an ``application`` +object that can be run with any WSGI server. For production, see +:doc:`/deploying/index`. For development, Werkzeug provides a server +through :func:`werkzeug.serving.run_simple`:: from werkzeug.serving import run_simple run_simple('localhost', 5000, application, use_reloader=True) Note that :func:`run_simple ` is not intended for -use in production. Use a :ref:`full-blown WSGI server `. +use in production. Use a production WSGI server. See :doc:`/deploying/index`. In order to use the interactive debugger, debugging must be enabled both on the application and the simple server. Here is the "hello world" example with @@ -79,7 +77,7 @@ with different configurations. Assuming the application is created inside a function and you can call that function to instantiate it, that is really easy to implement. In order to develop your application to support creating new instances in functions have a look at the -:ref:`app-factories` pattern. +:doc:`appfactories` pattern. A very common example would be creating applications per subdomain. For instance you configure your webserver to dispatch all requests for all diff --git a/docs/patterns/appfactories.rst b/docs/patterns/appfactories.rst index 28476a40..7ac4e110 100644 --- a/docs/patterns/appfactories.rst +++ b/docs/patterns/appfactories.rst @@ -1,10 +1,8 @@ -.. _app-factories: - Application Factories ===================== If you are already using packages and blueprints for your application -(:ref:`blueprints`) there are a couple of really nice ways to further improve +(:doc:`/blueprints`) there are a couple of really nice ways to further improve the experience. A common pattern is creating the application object when the blueprint is imported. But if you move the creation of this object into a function, you can then create multiple instances of this app later. diff --git a/docs/patterns/caching.rst b/docs/patterns/caching.rst index d6c8a02b..9bf7b72a 100644 --- a/docs/patterns/caching.rst +++ b/docs/patterns/caching.rst @@ -1,5 +1,3 @@ -.. _caching-pattern: - Caching ======= diff --git a/docs/patterns/deferredcallbacks.rst b/docs/patterns/deferredcallbacks.rst index a139c5b8..4ff8814b 100644 --- a/docs/patterns/deferredcallbacks.rst +++ b/docs/patterns/deferredcallbacks.rst @@ -1,5 +1,3 @@ -.. _deferred-callbacks: - Deferred Request Callbacks ========================== diff --git a/docs/patterns/distribute.rst b/docs/patterns/distribute.rst index 90cec080..83885df7 100644 --- a/docs/patterns/distribute.rst +++ b/docs/patterns/distribute.rst @@ -1,5 +1,3 @@ -.. _distribute-deployment: - Deploying with Setuptools ========================= @@ -23,14 +21,13 @@ Flask itself, and all the libraries you can find on PyPI are distributed with either setuptools or distutils. In this case we assume your application is called -:file:`yourapplication.py` and you are not using a module, but a :ref:`package -`. If you have not yet converted your application into -a package, head over to the :ref:`larger-applications` pattern to see -how this can be done. +:file:`yourapplication.py` and you are not using a module, but a +package. If you have not yet converted your application into a package, +head over to :doc:`packages` to see how this can be done. A working deployment with setuptools is the first step into more complex and more automated deployment scenarios. If you want to fully automate -the process, also read the :ref:`fabric-deployment` chapter. +the process, also read the :doc:`fabric` chapter. Basic Setup Script ------------------ @@ -38,8 +35,8 @@ Basic Setup Script Because you have Flask installed, you have setuptools available on your system. Flask already depends upon setuptools. -Standard disclaimer applies: :ref:`you better use a virtualenv -`. +Standard disclaimer applies: :ref:`use a virtualenv +`. Your setup code always goes into a file named :file:`setup.py` next to your application. The name of the file is only convention, but because diff --git a/docs/patterns/errorpages.rst b/docs/patterns/errorpages.rst index 7e43674c..cf7462af 100644 --- a/docs/patterns/errorpages.rst +++ b/docs/patterns/errorpages.rst @@ -1,5 +1,3 @@ -.. _errorpages: - Custom Error Pages ================== @@ -41,7 +39,7 @@ even if the application behaves correctly: Usually happens on programming errors or if the server is overloaded. A terribly good idea is to have a nice page there, because your application *will* fail sooner or later (see also: - :ref:`application-errors`). + :doc:`/errorhandling`). Error Handlers @@ -74,7 +72,7 @@ Here is an example implementation for a "404 Page Not Found" exception:: # note that we set the 404 status explicitly return render_template('404.html'), 404 -When using the :ref:`application factory pattern `:: +When using the :doc:`appfactories`:: from flask import Flask, render_template diff --git a/docs/patterns/fabric.rst b/docs/patterns/fabric.rst index 30837931..0cd39ddc 100644 --- a/docs/patterns/fabric.rst +++ b/docs/patterns/fabric.rst @@ -1,12 +1,10 @@ -.. _fabric-deployment: - Deploying with Fabric ===================== `Fabric`_ is a tool for Python similar to Makefiles but with the ability to execute commands on a remote server. In combination with a properly -set up Python package (:ref:`larger-applications`) and a good concept for -configurations (:ref:`config`) it is very easy to deploy Flask +set up Python package (:doc:`packages`) and a good concept for +configurations (:doc:`/config`) it is very easy to deploy Flask applications to external servers. Before we get started, here a quick checklist of things we have to ensure @@ -15,7 +13,7 @@ upfront: - Fabric 1.0 has to be installed locally. This tutorial assumes the latest version of Fabric. - The application already has to be a package and requires a working - :file:`setup.py` file (:ref:`distribute-deployment`). + :file:`setup.py` file (:doc:`distribute`). - In the following example we are using `mod_wsgi` for the remote servers. You can of course use your own favourite server there, but for this example we chose Apache + `mod_wsgi` because it's very easy @@ -101,7 +99,7 @@ To setup a new server you would roughly do these steps: 3. Create a new Apache config for ``yourapplication`` and activate it. Make sure to activate watching for changes of the ``.wsgi`` file so that we can automatically reload the application by touching it. - (See :ref:`mod_wsgi-deployment` for more information) + See :doc:`/deploying/mod_wsgi`. So now the question is, where do the :file:`application.wsgi` and :file:`application.cfg` files come from? @@ -124,7 +122,7 @@ the config at that environment variable:: app.config.from_object('yourapplication.default_config') app.config.from_envvar('YOURAPPLICATION_CONFIG') -This approach is explained in detail in the :ref:`config` section of the +This approach is explained in detail in the :doc:`/config` section of the documentation. The Configuration File diff --git a/docs/patterns/fileuploads.rst b/docs/patterns/fileuploads.rst index 6fa21bee..43ee5965 100644 --- a/docs/patterns/fileuploads.rst +++ b/docs/patterns/fileuploads.rst @@ -1,5 +1,3 @@ -.. _uploading-files: - Uploading Files =============== @@ -39,7 +37,7 @@ Why do we limit the extensions that are allowed? You probably don't want your users to be able to upload everything there if the server is directly sending out the data to the client. That way you can make sure that users are not able to upload HTML files that would cause XSS problems (see -:ref:`xss`). Also make sure to disallow ``.php`` files if the server +:ref:`security-xss`). Also make sure to disallow ``.php`` files if the server executes them, but who has PHP installed on their server, right? :) Next the functions that check if an extension is valid and that uploads diff --git a/docs/patterns/flashing.rst b/docs/patterns/flashing.rst index 4c8a7870..8eb6b3ac 100644 --- a/docs/patterns/flashing.rst +++ b/docs/patterns/flashing.rst @@ -1,5 +1,3 @@ -.. _message-flashing-pattern: - Message Flashing ================ diff --git a/docs/patterns/index.rst b/docs/patterns/index.rst index d24147fd..a9727e3d 100644 --- a/docs/patterns/index.rst +++ b/docs/patterns/index.rst @@ -1,5 +1,3 @@ -.. _patterns: - Patterns for Flask ================== diff --git a/docs/patterns/mongokit.rst b/docs/patterns/mongokit.rst deleted file mode 100644 index cf072d5d..00000000 --- a/docs/patterns/mongokit.rst +++ /dev/null @@ -1,7 +0,0 @@ -:orphan: - -MongoDB with MongoKit -===================== - -MongoKit is no longer maintained. See :doc:`/patterns/mongoengine` -instead. diff --git a/docs/patterns/packages.rst b/docs/patterns/packages.rst index e9d14ca5..ab4db424 100644 --- a/docs/patterns/packages.rst +++ b/docs/patterns/packages.rst @@ -1,7 +1,5 @@ -.. _larger-applications: - -Larger Applications -=================== +Large Applications as Packages +============================== Imagine a simple flask application structure that looks like this:: @@ -17,7 +15,7 @@ Imagine a simple flask application structure that looks like this:: While this is fine for small applications, for larger applications it's a good idea to use a package instead of a module. -The :ref:`tutorial ` is structured to use the package pattern, +The :doc:`/tutorial/index` is structured to use the package pattern, see the :gh:`example code `. Simple Packages @@ -129,15 +127,13 @@ You should then end up with something like that:: There are still some problems with that approach but if you want to use decorators there is no way around that. Check out the - :ref:`becomingbig` section for some inspiration how to deal with that. + :doc:`/becomingbig` section for some inspiration how to deal with that. -.. _working-with-modules: - Working with Blueprints ----------------------- If you have larger applications it's recommended to divide them into smaller groups where each group is implemented with the help of a blueprint. For a gentle introduction into this topic refer to the -:ref:`blueprints` chapter of the documentation. +:doc:`/blueprints` chapter of the documentation. diff --git a/docs/patterns/sqlalchemy.rst b/docs/patterns/sqlalchemy.rst index f240e5da..734d550c 100644 --- a/docs/patterns/sqlalchemy.rst +++ b/docs/patterns/sqlalchemy.rst @@ -1,12 +1,10 @@ -.. _sqlalchemy-pattern: - SQLAlchemy in Flask =================== Many people prefer `SQLAlchemy`_ for database access. In this case it's encouraged to use a package instead of a module for your flask application -and drop the models into a separate module (:ref:`larger-applications`). -While that is not necessary, it makes a lot of sense. +and drop the models into a separate module (:doc:`packages`). While that +is not necessary, it makes a lot of sense. There are four very common ways to use SQLAlchemy. I will outline each of them here: @@ -109,8 +107,7 @@ Querying is simple as well: .. _SQLAlchemy: https://www.sqlalchemy.org/ -.. _declarative: - https://docs.sqlalchemy.org/en/latest/orm/extensions/declarative/ +.. _declarative: https://docs.sqlalchemy.org/en/latest/orm/extensions/declarative/ Manual Object Relational Mapping -------------------------------- diff --git a/docs/patterns/sqlite3.rst b/docs/patterns/sqlite3.rst index eecaaae8..8cf596d3 100644 --- a/docs/patterns/sqlite3.rst +++ b/docs/patterns/sqlite3.rst @@ -1,5 +1,3 @@ -.. _sqlite3: - Using SQLite 3 with Flask ========================= @@ -62,7 +60,6 @@ the application context by hand:: with app.app_context(): # now you can use get_db() -.. _easy-querying: Easy Querying ------------- diff --git a/docs/patterns/templateinheritance.rst b/docs/patterns/templateinheritance.rst index dbcb4163..bb5cba27 100644 --- a/docs/patterns/templateinheritance.rst +++ b/docs/patterns/templateinheritance.rst @@ -1,5 +1,3 @@ -.. _template-inheritance: - Template Inheritance ==================== diff --git a/docs/patterns/viewdecorators.rst b/docs/patterns/viewdecorators.rst index ff88fceb..b0960b2d 100644 --- a/docs/patterns/viewdecorators.rst +++ b/docs/patterns/viewdecorators.rst @@ -59,7 +59,7 @@ Caching Decorator Imagine you have a view function that does an expensive calculation and because of that you would like to cache the generated results for a certain amount of time. A decorator would be nice for that. We're -assuming you have set up a cache like mentioned in :ref:`caching-pattern`. +assuming you have set up a cache like mentioned in :doc:`caching`. Here is an example cache function. It generates the cache key from a specific prefix (actually a format string) and the current path of the @@ -96,8 +96,8 @@ Here the code:: return decorated_function return decorator -Notice that this assumes an instantiated `cache` object is available, see -:ref:`caching-pattern` for more information. +Notice that this assumes an instantiated ``cache`` object is available, see +:doc:`caching`. Templating Decorator diff --git a/docs/patterns/wtforms.rst b/docs/patterns/wtforms.rst index cb482e64..e5fd500d 100644 --- a/docs/patterns/wtforms.rst +++ b/docs/patterns/wtforms.rst @@ -9,7 +9,7 @@ forms, you might want to give it a try. When you are working with WTForms you have to define your forms as classes first. I recommend breaking up the application into multiple modules -(:ref:`larger-applications`) for that and adding a separate module for the +(:doc:`packages`) for that and adding a separate module for the forms. .. admonition:: Getting the most out of WTForms with an Extension @@ -55,7 +55,7 @@ In the view function, the usage of this form looks like this:: return render_template('register.html', form=form) Notice we're implying that the view is using SQLAlchemy here -(:ref:`sqlalchemy-pattern`), but that's not a requirement, of course. Adapt +(:doc:`sqlalchemy`), but that's not a requirement, of course. Adapt the code as necessary. Things to remember: diff --git a/docs/quickstart.rst b/docs/quickstart.rst index eb699886..fdbad6e5 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -1,5 +1,3 @@ -.. _quickstart: - Quickstart ========== @@ -61,9 +59,9 @@ And on PowerShell:: PS C:\path\to\app> $env:FLASK_APP = "hello.py" -This launches a very simple builtin server, which is good enough for testing -but probably not what you want to use in production. For deployment options see -:ref:`deployment`. +This launches a very simple builtin server, which is good enough for +testing but probably not what you want to use in production. For +deployment options see :doc:`deploying/index`. Now head over to http://127.0.0.1:5000/, and you should see your hello world greeting. @@ -118,7 +116,7 @@ The most common reason is a typo or because you did not actually create an Debug Mode ---------- -(Want to just log errors and stack traces? See :ref:`application-errors`) +(Want to just log errors and stack traces? See :doc:`errorhandling`) 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. @@ -432,9 +430,9 @@ Inside templates you also have access to the :class:`~flask.request`, as well as the :func:`~flask.get_flashed_messages` function. Templates are especially useful if inheritance is used. If you want to -know how that works, head over to the :ref:`template-inheritance` pattern -documentation. Basically template inheritance makes it possible to keep -certain elements on each page (like header, navigation and footer). +know how that works, see :doc:`patterns/templateinheritance`. Basically +template inheritance makes it possible to keep certain elements on each +page (like header, navigation and footer). Automatic escaping is enabled, so if ``name`` contains HTML it will be escaped automatically. If you can trust a variable and you know that it will be @@ -461,9 +459,8 @@ Here is a basic introduction to how the :class:`~markupsafe.Markup` class works: autoescaping disabled. .. [#] Unsure what that :class:`~flask.g` object is? It's something in which - you can store information for your own needs, check the documentation of - that object (:class:`~flask.g`) and the :ref:`sqlite3` for more - information. + you can store information for your own needs. See the documentation + for :class:`flask.g` and :doc:`patterns/sqlite3`. Accessing Request Data @@ -613,7 +610,7 @@ Werkzeug provides for you:: file.save(f"/var/www/uploads/{secure_filename(f.filename)}") ... -For some better examples, checkout the :ref:`uploading-files` pattern. +For some better examples, see :doc:`patterns/fileuploads`. Cookies ``````` @@ -653,7 +650,7 @@ the :meth:`~flask.make_response` function and then modify it. Sometimes you might want to set a cookie at a point where the response object does not exist yet. This is possible by utilizing the -:ref:`deferred-callbacks` pattern. +:doc:`patterns/deferredcallbacks` pattern. For this also see :ref:`about-responses`. @@ -693,7 +690,7 @@ Note the ``404`` after the :func:`~flask.render_template` call. This tells Flask that the status code of that page should be 404 which means not found. By default 200 is assumed which translates to: all went well. -See :ref:`error-handlers` for more details. +See :doc:`errorhandling` for more details. .. _about-responses: @@ -857,8 +854,8 @@ template to expose the message. To flash a message use the :func:`~flask.flash` method, to get hold of the messages you can use :func:`~flask.get_flashed_messages` which is also -available in the templates. Check out the :ref:`message-flashing-pattern` -for a full example. +available in the templates. See :doc:`patterns/flashing` for a full +example. Logging ------- @@ -887,7 +884,8 @@ The attached :attr:`~flask.Flask.logger` is a standard logging :class:`~logging.Logger`, so head over to the official :mod:`logging` docs for more information. -Read more on :ref:`application-errors`. +See :doc:`errorhandling`. + Hooking in WSGI Middleware -------------------------- @@ -913,9 +911,9 @@ Extensions are packages that help you accomplish common tasks. For example, Flask-SQLAlchemy provides SQLAlchemy support that makes it simple and easy to use with Flask. -For more on Flask extensions, have a look at :ref:`extensions`. +For more on Flask extensions, see :doc:`extensions`. Deploying to a Web Server ------------------------- -Ready to deploy your new Flask app? Go to :ref:`deployment`. +Ready to deploy your new Flask app? See :doc:`deploying/index`. diff --git a/docs/reqcontext.rst b/docs/reqcontext.rst index 811e5950..31a83cff 100644 --- a/docs/reqcontext.rst +++ b/docs/reqcontext.rst @@ -1,7 +1,5 @@ .. currentmodule:: flask -.. _request-context: - The Request Context =================== @@ -257,7 +255,7 @@ exceptions where it is good to know that this object is actually a proxy: If you want to perform instance checks, you have to do that on the object being proxied. - The reference to the proxied object is needed in some situations, - such as sending :ref:`signals` or passing data to a background + such as sending :doc:`signals` or passing data to a background thread. If you need to access the underlying object that is proxied, use the diff --git a/docs/security.rst b/docs/security.rst index 44c095ac..57a7b422 100644 --- a/docs/security.rst +++ b/docs/security.rst @@ -5,7 +5,7 @@ Web applications usually face all kinds of security problems and it's very hard to get everything right. Flask tries to solve a few of these things for you, but there are a couple more you have to take care of yourself. -.. _xss: +.. _security-xss: Cross-Site Scripting (XSS) -------------------------- @@ -101,7 +101,7 @@ compare the two tokens and ensure they are equal. Why does Flask not do that for you? The ideal place for this to happen is the form validation framework, which does not exist in Flask. -.. _json-security: +.. _security-json: JSON Security ------------- diff --git a/docs/shell.rst b/docs/shell.rst index c863a77d..47efba37 100644 --- a/docs/shell.rst +++ b/docs/shell.rst @@ -1,5 +1,3 @@ -.. _shell: - Working with the Shell ====================== @@ -23,7 +21,7 @@ that these functions are not only there for interactive shell usage, but also for unit testing and other situations that require a faked request context. -Generally it's recommended that you read the :ref:`request-context` +Generally it's recommended that you read the :doc:`reqcontext` chapter of the documentation first. Command Line Interface @@ -34,7 +32,7 @@ Starting with Flask 0.11 the recommended way to work with the shell is the For instance the shell is automatically initialized with a loaded application context. -For more information see :ref:`cli`. +For more information see :doc:`/cli`. Creating a Request Context -------------------------- diff --git a/docs/signals.rst b/docs/signals.rst index 7c1aef1e..1e5cdd65 100644 --- a/docs/signals.rst +++ b/docs/signals.rst @@ -1,5 +1,3 @@ -.. _signals: - Signals ======= @@ -162,7 +160,7 @@ function, you can pass ``current_app._get_current_object()`` as sender. Signals and Flask's Request Context ----------------------------------- -Signals fully support :ref:`request-context` when receiving signals. +Signals fully support :doc:`reqcontext` when receiving signals. Context-local variables are consistently available between :data:`~flask.request_started` and :data:`~flask.request_finished`, so you can rely on :class:`flask.g` and others as needed. Note the limitations described diff --git a/docs/templating.rst b/docs/templating.rst index 5ae4fd72..bf18426b 100644 --- a/docs/templating.rst +++ b/docs/templating.rst @@ -1,5 +1,3 @@ -.. _templates: - Templates ========= @@ -139,7 +137,7 @@ carry specific meanings in documents on their own you have to replace them by so called "entities" if you want to use them for text. Not doing so would not only cause user frustration by the inability to use these characters in text, but can also lead to security problems. (see -:ref:`xss`) +:ref:`security-xss`) Sometimes however you will need to disable autoescaping in templates. This can be the case if you want to explicitly inject HTML into pages, for diff --git a/docs/testing.rst b/docs/testing.rst index 881e73bb..6910aa48 100644 --- a/docs/testing.rst +++ b/docs/testing.rst @@ -1,5 +1,3 @@ -.. _testing: - Testing Flask Applications ========================== @@ -26,8 +24,8 @@ The Application --------------- First, we need an application to test; we will use the application from -the :ref:`tutorial`. If you don't have that application yet, get the -source code from :gh:`the examples `. +the :doc:`tutorial/index`. If you don't have that application yet, get +the source code from :gh:`the examples `. So that we can import the module ``flaskr`` correctly, we need to run ``pip install -e .`` in the folder ``tutorial``. @@ -239,7 +237,7 @@ way. If you want to test your application with different configurations and there does not seem to be a good way to do that, consider switching to -application factories (see :ref:`app-factories`). +application factories (see :doc:`patterns/appfactories`). Note however that if you are using a test request context, the :meth:`~flask.Flask.before_request` and :meth:`~flask.Flask.after_request` diff --git a/docs/tutorial/database.rst b/docs/tutorial/database.rst index 942341dc..b094909e 100644 --- a/docs/tutorial/database.rst +++ b/docs/tutorial/database.rst @@ -142,7 +142,7 @@ read from the file. :func:`click.command` defines a command line command called ``init-db`` that calls the ``init_db`` function and shows a success message to the -user. You can read :ref:`cli` to learn more about writing commands. +user. You can read :doc:`/cli` to learn more about writing commands. Register with the Application @@ -196,9 +196,9 @@ previous page. If you're still running the server from the previous page, you can either stop the server, or run this command in a new terminal. If you use a new terminal, remember to change to your project directory - and activate the env as described in :ref:`install-activate-env`. - You'll also need to set ``FLASK_APP`` and ``FLASK_ENV`` as shown on - the previous page. + and activate the env as described in :doc:`/installation`. You'll + also need to set ``FLASK_APP`` and ``FLASK_ENV`` as shown on the + previous page. Run the ``init-db`` command: diff --git a/docs/tutorial/index.rst b/docs/tutorial/index.rst index 9b43c510..103c27a8 100644 --- a/docs/tutorial/index.rst +++ b/docs/tutorial/index.rst @@ -1,5 +1,3 @@ -.. _tutorial: - Tutorial ======== @@ -35,11 +33,11 @@ tutorial`_ in the Python docs is a great way to learn or review first. .. _official tutorial: https://docs.python.org/3/tutorial/ While it's designed to give a good starting point, the tutorial doesn't -cover all of Flask's features. Check out the :ref:`quickstart` for an +cover all of Flask's features. Check out the :doc:`/quickstart` for an overview of what Flask can do, then dive into the docs to find out more. The tutorial only uses what's provided by Flask and Python. In another -project, you might decide to use :ref:`extensions` or other libraries to -make some tasks simpler. +project, you might decide to use :doc:`/extensions` or other libraries +to make some tasks simpler. .. image:: flaskr_login.png :align: center diff --git a/docs/tutorial/next.rst b/docs/tutorial/next.rst index 07bbc048..d41e8ef2 100644 --- a/docs/tutorial/next.rst +++ b/docs/tutorial/next.rst @@ -9,11 +9,11 @@ different due to the step-by-step nature of the tutorial. There's a lot more to Flask than what you've seen so far. Even so, you're now equipped to start developing your own web applications. Check -out the :ref:`quickstart` for an overview of what Flask can do, then +out the :doc:`/quickstart` for an overview of what Flask can do, then dive into the docs to keep learning. Flask uses `Jinja`_, `Click`_, `Werkzeug`_, and `ItsDangerous`_ behind the scenes, and they all have their own documentation too. You'll also be interested in -:ref:`extensions` which make tasks like working with the database or +:doc:`/extensions` which make tasks like working with the database or validating form data easier and more powerful. If you want to keep developing your Flaskr project, here are some ideas diff --git a/docs/views.rst b/docs/views.rst index ed75c027..1d2daec7 100644 --- a/docs/views.rst +++ b/docs/views.rst @@ -1,5 +1,3 @@ -.. _views: - Pluggable Views =============== diff --git a/src/flask/app.py b/src/flask/app.py index 75b002bb..1143f20d 100644 --- a/src/flask/app.py +++ b/src/flask/app.py @@ -868,7 +868,7 @@ class Flask(_PackageBoundObject): Do not use ``run()`` in a production setting. It is not intended to meet security and performance requirements for a production server. - Instead, see :ref:`deployment` for WSGI server recommendations. + Instead, see :doc:`/deploying/index` for WSGI server recommendations. If the :attr:`debug` flag is set the server will automatically reload for code changes and show a debugger in case an exception happened. @@ -980,7 +980,7 @@ class Flask(_PackageBoundObject): def test_client(self, use_cookies=True, **kwargs): """Creates a test client for this application. For information - about unit testing head over to :ref:`testing`. + about unit testing head over to :doc:`/testing`. Note that if you are testing for assertions or exceptions in your application code, you must set ``app.testing = True`` in order for the diff --git a/src/flask/blueprints.py b/src/flask/blueprints.py index c8dfa375..01bcc233 100644 --- a/src/flask/blueprints.py +++ b/src/flask/blueprints.py @@ -90,7 +90,7 @@ class Blueprint(_PackageBoundObject): that is called with :class:`~flask.blueprints.BlueprintSetupState` when the blueprint is registered on an application. - See :ref:`blueprints` for more information. + See :doc:`/blueprints` for more information. .. versionchanged:: 1.1.0 Blueprints have a ``cli`` group to register nested CLI commands. diff --git a/src/flask/cli.py b/src/flask/cli.py index 30e181ad..83bd4a83 100644 --- a/src/flask/cli.py +++ b/src/flask/cli.py @@ -444,9 +444,7 @@ class FlaskGroup(AppGroup): loading more commands from the configured Flask app. Normally a developer does not have to interface with this class but there are some very advanced use cases for which it makes sense to create an - instance of this. - - For information as of why this is useful see :ref:`custom-scripts`. + instance of this. see :ref:`custom-scripts`. :param add_default_commands: if this is True then the default run and shell commands will be added. diff --git a/src/flask/helpers.py b/src/flask/helpers.py index 07c59b28..42c9e0dc 100644 --- a/src/flask/helpers.py +++ b/src/flask/helpers.py @@ -221,7 +221,7 @@ def url_for(endpoint, **values): url_for('.index') - For more information, head over to the :ref:`Quickstart `. + See :ref:`url-building`. Configuration values ``APPLICATION_ROOT`` and ``SERVER_NAME`` are only used when generating URLs outside of a request context. @@ -278,9 +278,9 @@ def url_for(endpoint, **values): :param _scheme: a string specifying the desired URL scheme. The `_external` parameter must be set to ``True`` or a :exc:`ValueError` is raised. The default behavior uses the same scheme as the current request, or - ``PREFERRED_URL_SCHEME`` from the :ref:`app configuration ` if no - request context is available. As of Werkzeug 0.10, this also can be set - to an empty string to build protocol-relative URLs. + :data:`PREFERRED_URL_SCHEME` if no request context is available. + This also can be set to an empty string to build protocol-relative + URLs. :param _anchor: if provided this is added as anchor to the URL. :param _method: if provided this explicitly specifies an HTTP method. """ @@ -428,7 +428,7 @@ def get_flashed_messages(with_categories=False, category_filter=()): * `category_filter` filters the messages down to only those matching the provided categories. - See :ref:`message-flashing-pattern` for examples. + See :doc:`/patterns/flashing` for examples. .. versionchanged:: 0.3 `with_categories` parameter added. diff --git a/src/flask/json/__init__.py b/src/flask/json/__init__.py index e2fdfcff..5c698ef0 100644 --- a/src/flask/json/__init__.py +++ b/src/flask/json/__init__.py @@ -331,8 +331,9 @@ def jsonify(*args, **kwargs): .. versionchanged:: 0.11 - Added support for serializing top-level arrays. This introduces a - security risk in ancient browsers. See :ref:`json-security` for details. + Added support for serializing top-level arrays. This introduces + a security risk in ancient browsers. See :ref:`security-json` + for details. This function's response will be pretty printed if the ``JSONIFY_PRETTYPRINT_REGULAR`` config parameter is set to True or the diff --git a/src/flask/testing.py b/src/flask/testing.py index 3b9e3095..2da66d79 100644 --- a/src/flask/testing.py +++ b/src/flask/testing.py @@ -94,7 +94,7 @@ class FlaskClient(Client): set after instantiation of the `app.test_client()` object in `client.environ_base`. - Basic usage is outlined in the :ref:`testing` chapter. + Basic usage is outlined in the :doc:`/testing` chapter. """ preserve_context = False