remove unused ref directives

replace page refs with doc directives

docs/advanced_foreword.rst

@@ -1,5 +1,3 @@
-.. _advanced_foreword:
-
 Foreword for Experienced Programmers
 ====================================
 

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
+    The configuration variable :data:`JSON_SORT_KEYS` can be set to
-    set to false to stop Flask from auto-sorting keys.  By default sorting
+    ``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
+    Notice that disabling key sorting can cause issues when using
-    based HTTP caches and Python's hash randomization feature.
+    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
 ---------------------

docs/appcontext.rst

@@ -1,7 +1,5 @@
 .. currentmodule:: flask
 
-.. _app-context:
-
 The Application Context
 =======================
 

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
+The :doc:`/api` docs are full of available overrides, hook points, and
-:ref:`signals`. You can provide custom classes for things like the
+: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

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
+objects?  You can do that (see :doc:`/patterns/appdispatch`), but your
-will have separate configs and will be managed at the WSGI layer.
+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`.

docs/changelog.rst

@@ -1,4 +1,4 @@
-Changelog
+Changes
-=========
+=======
 
 .. include:: ../CHANGES.rst

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

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 <app-dispatch>`
+    ``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/
 

docs/deploying/fastcgi.rst

@@ -1,5 +1,3 @@
-.. _deploying-fastcgi:
-
 FastCGI
 =======
 

docs/deploying/index.rst

@@ -1,5 +1,3 @@
-.. _deployment:
-
 Deployment Options
 ==================
 

docs/deploying/mod_wsgi.rst

@@ -1,5 +1,3 @@
-.. _mod_wsgi-deployment:
-
 mod_wsgi (Apache)
 =================
 

docs/deploying/uwsgi.rst

@@ -1,5 +1,3 @@
-.. _deploying-uwsgi:
-
 uWSGI
 =====
 

docs/deploying/wsgi-standalone.rst

@@ -1,5 +1,3 @@
-.. _deploying-wsgi-standalone:
-
 Standalone WSGI Containers
 ==========================
 

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.
 
 

docs/errorhandling.rst

@@ -1,5 +1,3 @@
-.. _application-errors:
-
 Application Errors
 ==================
 
@@ -68,7 +66,6 @@ Follow-up reads:
 * `Getting started with Sentry <https://docs.sentry.io/quickstart/?platform=python>`_
 * `Flask-specific documentation <https://docs.sentry.io/platforms/python/flask/>`_.
 
-.. _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.
 

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
+:doc:`/patterns/appfactories` pattern to create their application as
-unittests and to support multiple configurations.  Because of that it is
+needed to aid unittests and to support multiple configurations. Because
-crucial that your application supports that kind of behavior.
+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
+documentation suggests (:doc:`/patterns/sqlite3`). So how does the
-know the name of the application object?
+extension know the name of the application object?
 
 Quite simple: you pass it to it.
 

docs/extensions.rst

@@ -1,5 +1,3 @@
-.. _extensions:
-
 Extensions
 ==========
 

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
+in that, check out the :doc:`becomingbig` chapter.  If you are curious about
-the Flask design principles, head over to the section about :ref:`design`.
+the Flask design principles, head over to the section about :doc:`design`.
-
-Continue to :ref:`installation`, the :ref:`quickstart`, or the
-:ref:`advanced_foreword`.

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`
+Welcome to Flask's documentation. Get started with :doc:`installation`
-and then get an overview with the :ref:`quickstart`. There is also a
+and then get an overview with the :doc:`quickstart`. There is also a
-more detailed :ref:`tutorial` that shows how to create a small but
+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
+:doc:`patterns/index` section. The rest of the docs describe each
-Flask in detail, with a full reference in the :ref:`api` section.
+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:

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

docs/license.rst

@@ -4,9 +4,9 @@ License
 Source License
 --------------
 
-This license applies to all files in the Flask repository and source
+The BSD-3-Clause license applies to all files in the Flask repository
-distribution. This includes Flask's source code, the examples, and
+and source distribution. This includes Flask's source code, the
-tests, as well as the documentation.
+examples, and tests, as well as the documentation.
 
 .. include:: ../LICENSE.rst
 

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
+The fundamental difference from :doc:`packages` is that in this case you
-<larger-applications>` is that in this case you are running the same or
+are running the same or different Flask applications that are entirely
-different Flask applications that are entirely isolated from each other.
+isolated from each other. They run different configurations and are
-They run different configurations and are dispatched on the WSGI level.
+dispatched on the WSGI level.
 
 
 Working with this Document
 --------------------------
 
-Each of the techniques and examples below results in an ``application`` object
+Each of the techniques and examples below results in an ``application``
-that can be run with any WSGI server.  For production, see :ref:`deployment`.
+object that can be run with any WSGI server. For production, see
-For development, Werkzeug provides a builtin server for development available
+:doc:`/deploying/index`. For development, Werkzeug provides a server
-at :func:`werkzeug.serving.run_simple`::
+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 <werkzeug.serving.run_simple>` is not intended for
-use in production.  Use a :ref:`full-blown WSGI server <deployment>`.
+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

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.

docs/patterns/caching.rst

@@ -1,5 +1,3 @@
-.. _caching-pattern:
-
 Caching
 =======
 

docs/patterns/deferredcallbacks.rst

@@ -1,5 +1,3 @@
-.. _deferred-callbacks:
-
 Deferred Request Callbacks
 ==========================
 

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
+:file:`yourapplication.py` and you are not using a module, but a
-<larger-applications>`. If you have not yet converted your application into
+package. If you have not yet converted your application into a package,
-a package, head over to the :ref:`larger-applications` pattern to see
+head over to :doc:`packages` to see how this can be done.
-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
-<virtualenv>`.
+<install-create-env>`.
 
 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

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 <app-factories>`::
+When using the :doc:`appfactories`::
 
     from flask import Flask, render_template
 

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
+set up Python package (:doc:`packages`) and a good concept for
-configurations (:ref:`config`) it is very easy to deploy Flask
+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

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

docs/patterns/flashing.rst

@@ -1,5 +1,3 @@
-.. _message-flashing-pattern:
-
 Message Flashing
 ================
 

docs/patterns/index.rst

@@ -1,5 +1,3 @@
-.. _patterns:
-
 Patterns for Flask
 ==================
 

docs/patterns/mongokit.rst

@@ -1,7 +0,0 @@
-:orphan:
-
-MongoDB with MongoKit
-=====================
-
-MongoKit is no longer maintained. See :doc:`/patterns/mongoengine`
-instead.

docs/patterns/packages.rst

@@ -1,7 +1,5 @@
-.. _larger-applications:
+Large Applications as Packages
-
+==============================
-Larger Applications
-===================
 
 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 <tutorial>` is structured to use the package pattern,
+The :doc:`/tutorial/index` is structured to use the package pattern,
 see the :gh:`example code <examples/tutorial>`.
 
 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.

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`).
+and drop the models into a separate module (:doc:`packages`). While that
-While that is not necessary, it makes a lot of sense.
+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:
 <User 'admin'>
 
 .. _SQLAlchemy: https://www.sqlalchemy.org/
-.. _declarative:
+.. _declarative: https://docs.sqlalchemy.org/en/latest/orm/extensions/declarative/
-   https://docs.sqlalchemy.org/en/latest/orm/extensions/declarative/
 
 Manual Object Relational Mapping
 --------------------------------

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

docs/patterns/templateinheritance.rst

@@ -1,5 +1,3 @@
-.. _template-inheritance:
-
 Template Inheritance
 ====================
 

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
+Notice that this assumes an instantiated ``cache`` object is available, see
-:ref:`caching-pattern` for more information.
+:doc:`caching`.
 
 
 Templating Decorator

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:

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
+This launches a very simple builtin server, which is good enough for
-but probably not what you want to use in production. For deployment options see
+testing but probably not what you want to use in production. For
-:ref:`deployment`.
+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
+know how that works, see :doc:`patterns/templateinheritance`. Basically
-documentation.  Basically template inheritance makes it possible to keep
+template inheritance makes it possible to keep certain elements on each
-certain elements on each page (like header, navigation and footer).
+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
+   you can store information for your own needs. See the documentation
-   that object (:class:`~flask.g`) and the :ref:`sqlite3` for more
+   for :class:`flask.g` and :doc:`patterns/sqlite3`.
-   information.
 
 
 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`
+available in the templates. See :doc:`patterns/flashing` for a full
-for a full example.
+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`.

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

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

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

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

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

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
+the :doc:`tutorial/index`. If you don't have that application yet, get
-source code from :gh:`the examples <examples/tutorial>`.
+the source code from :gh:`the examples <examples/tutorial>`.
 
 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`

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`.
+    and activate the env as described in :doc:`/installation`. You'll
-    You'll also need to set ``FLASK_APP`` and ``FLASK_ENV`` as shown on
+    also need to set ``FLASK_APP`` and ``FLASK_ENV`` as shown on the
-    the previous page.
+    previous page.
 
 Run the ``init-db`` command:
 

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
+project, you might decide to use :doc:`/extensions` or other libraries
-make some tasks simpler.
+to make some tasks simpler.
 
 .. image:: flaskr_login.png
     :align: center

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

docs/views.rst

@@ -1,5 +1,3 @@
-.. _views:
-
 Pluggable Views
 ===============
 

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

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.

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.
+    instance of this. see :ref:`custom-scripts`.
-
-    For information as of why this is useful see :ref:`custom-scripts`.
 
     :param add_default_commands: if this is True then the default run and
         shell commands will be added.

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 <url-building>`.
+    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 <config>` if no
+      :data:`PREFERRED_URL_SCHEME` if no request context is available.
-      request context is available. As of Werkzeug 0.10, this also can be set
+      This also can be set to an empty string to build protocol-relative
-      to an empty string to build protocol-relative URLs.
+      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.

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
+        Added support for serializing top-level arrays. This introduces
-       security risk in ancient browsers. See :ref:`json-security` for details.
+        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

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