diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 7e7d4382..a68aa31c 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -9,7 +9,7 @@ Support questions Please, don't use the issue tracker for this. Use one of the following resources for questions about your own code: -* The ``#get-help`` channel on our Discord chat: https://discord.gg/t6rrQZH +* The ``#get-help`` channel on our Discord chat: https://discordapp.com/invite/t6rrQZH * The IRC channel ``#pocoo`` on FreeNode is linked to Discord, but Discord is preferred. @@ -24,15 +24,15 @@ Reporting issues ---------------- - Describe what you expected to happen. -- If possible, include a `minimal, complete, and verifiable example`_ to help - us identify the issue. This also helps check that the issue is not with your - own code. +- If possible, include a `minimal reproducible example`_ to help us + identify the issue. This also helps check that the issue is not with + your own code. - Describe what actually happened. Include the full traceback if there was an exception. - List your Python, Flask, and Werkzeug versions. If possible, check if this issue is already fixed in the repository. -.. _minimal, complete, and verifiable example: https://stackoverflow.com/help/mcve +.. _minimal reproducible example: https://stackoverflow.com/help/minimal-reproducible-example Submitting patches ------------------ @@ -76,10 +76,10 @@ First time setup .. _GitHub account: https://github.com/join .. _latest version of git: https://git-scm.com/downloads -.. _username: https://help.github.com/articles/setting-your-username-in-git/ -.. _email: https://help.github.com/articles/setting-your-email-in-git/ +.. _username: https://help.github.com/en/articles/setting-your-username-in-git +.. _email: https://help.github.com/en/articles/setting-your-commit-email-address-in-git .. _Fork: https://github.com/pallets/flask/fork -.. _Clone: https://help.github.com/articles/fork-a-repo/#step-2-create-a-local-clone-of-your-fork +.. _Clone: https://help.github.com/en/articles/fork-a-repo#step-2-create-a-local-clone-of-your-fork Start coding ~~~~~~~~~~~~ @@ -96,8 +96,8 @@ Start coding git checkout -b your-branch-name origin/master - Using your favorite editor, make your changes, `committing as you go`_. -- Try to follow `PEP8`_, but you may ignore the line length limit if following - it would make the code uglier. +- Try to follow `PEP8`_. We have a pre-commit config and tests that will + ensure the code follows our style guide. - Include tests that cover any code changes you make. Make sure the test fails without your patch. `Run the tests. `_. - Push your commits to GitHub and `create a pull request`_ by using:: @@ -106,9 +106,9 @@ Start coding - Celebrate 🎉 -.. _committing as you go: http://dont-be-afraid-to-commit.readthedocs.io/en/latest/git/commandlinegit.html#commit-your-changes +.. _committing as you go: https://dont-be-afraid-to-commit.readthedocs.io/en/latest/git/commandlinegit.html#commit-your-changes .. _PEP8: https://pep8.org/ -.. _create a pull request: https://help.github.com/articles/creating-a-pull-request/ +.. _create a pull request: https://help.github.com/en/articles/creating-a-pull-request .. _contributing-testsuite: @@ -157,20 +157,9 @@ Build the docs in the ``docs`` directory using Sphinx:: Open ``_build/html/index.html`` in your browser to view the docs. -Read more about `Sphinx `_. +Read more about `Sphinx `_. -make targets -~~~~~~~~~~~~ - -Flask provides a ``Makefile`` with various shortcuts. They will ensure that -all dependencies are installed. - -- ``make test`` runs the basic test suite with ``pytest`` -- ``make cov`` runs the basic test suite with ``coverage`` -- ``make test-all`` runs the full test suite with ``tox`` -- ``make docs`` builds the HTML documentation - Caution: zero-padded file modes ------------------------------- diff --git a/docs/api.rst b/docs/api.rst index c3eda1cf..3f5dbf8b 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -43,9 +43,9 @@ Incoming Request Data .. attribute:: base_url .. attribute:: url_root - Provides different ways to look at the current `IRI - `_. Imagine your application is - listening on the following application root:: + Provides different ways to look at the current :rfc:`3987`. + Imagine your application is listening on the following application + root:: http://www.example.com/myapplication diff --git a/docs/becomingbig.rst b/docs/becomingbig.rst index 16dea1da..201be2e8 100644 --- a/docs/becomingbig.rst +++ b/docs/becomingbig.rst @@ -44,7 +44,7 @@ The :ref:`app-dispatch` chapter 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 -`_. +`_. Fork. ----- diff --git a/docs/cli.rst b/docs/cli.rst index 85b99fcb..abf15ff7 100644 --- a/docs/cli.rst +++ b/docs/cli.rst @@ -10,7 +10,7 @@ interface, in your virtualenv. Executed from the terminal, this script gives access to built-in, extension, and application-defined commands. The ``--help`` option will give more information about any commands and options. -.. _Click: http://click.pocoo.org/ +.. _Click: https://click.palletsprojects.com/ Application Discovery @@ -340,7 +340,7 @@ they are installed. Entry points are specified in :file:`setup.py` :: ) -.. _entry point: https://packaging.python.org/tutorials/distributing-packages/#entry-points +.. _entry point: https://packaging.python.org/tutorials/packaging-projects/#entry-points Inside :file:`flask_my_extension/commands.py` you can then export a Click object:: @@ -409,7 +409,7 @@ script is available. Note that you don't need to set ``FLASK_APP``. :: The ``flask`` command, being separate from your code, does not have this issue and is recommended in most cases. -.. _console script: https://packaging.python.org/tutorials/distributing-packages/#console-scripts +.. _console script: https://packaging.python.org/tutorials/packaging-projects/#console-scripts PyCharm Integration diff --git a/docs/deploying/cgi.rst b/docs/deploying/cgi.rst index 503d9426..dbc8b08a 100644 --- a/docs/deploying/cgi.rst +++ b/docs/deploying/cgi.rst @@ -58,4 +58,4 @@ work in that case: For more information consult the documentation of your webserver. -.. _App Engine: https://developers.google.com/appengine/ +.. _App Engine: https://cloud.google.com/appengine/docs/ diff --git a/docs/deploying/index.rst b/docs/deploying/index.rst index edf5a256..5e98f98c 100644 --- a/docs/deploying/index.rst +++ b/docs/deploying/index.rst @@ -17,12 +17,9 @@ Hosted options -------------- - `Deploying Flask on Heroku `_ -- `Deploying Flask on OpenShift `_ -- `Deploying Flask on Webfaction `_ - `Deploying Flask on Google App Engine `_ - `Deploying Flask on AWS Elastic Beanstalk `_ -- `Sharing your Localhost Server with Localtunnel `_ -- `Deploying on Azure (IIS) `_ +- `Deploying on Azure (IIS) `_ - `Deploying on PythonAnywhere `_ Self-hosted options diff --git a/docs/deploying/uwsgi.rst b/docs/deploying/uwsgi.rst index 50c85fb2..7c7104f7 100644 --- a/docs/deploying/uwsgi.rst +++ b/docs/deploying/uwsgi.rst @@ -69,4 +69,4 @@ to have it in the URL root its a bit simpler:: .. _nginx: https://nginx.org/ .. _lighttpd: https://www.lighttpd.net/ .. _cherokee: http://cherokee-project.com/ -.. _uwsgi: http://projects.unbit.it/uwsgi/ +.. _uwsgi: https://uwsgi-docs.readthedocs.io/en/latest/ diff --git a/docs/deploying/wsgi-standalone.rst b/docs/deploying/wsgi-standalone.rst index a7719126..99ef2217 100644 --- a/docs/deploying/wsgi-standalone.rst +++ b/docs/deploying/wsgi-standalone.rst @@ -43,11 +43,10 @@ Running `uWSGI HTTP Router`_:: uwsgi --http 127.0.0.1:5000 --module myproject:app -For a more optimized setup, see `configuring uWSGI and NGINX`_. +For a more optimized setup, see :doc:`/deploying/uwsgi`. -.. _uWSGI: http://uwsgi-docs.readthedocs.io/en/latest/ -.. _uWSGI HTTP Router: http://uwsgi-docs.readthedocs.io/en/latest/HTTP.html#the-uwsgi-http-https-router -.. _configuring uWSGI and NGINX: uwsgi.html#starting-your-app-with-uwsgi +.. _uWSGI: https://uwsgi-docs.readthedocs.io/en/latest/ +.. _uWSGI HTTP Router: https://uwsgi-docs.readthedocs.io/en/latest/HTTP.html#the-uwsgi-http-https-router Gevent ------- @@ -86,7 +85,7 @@ application from ``myproject``:: twistd -n web --port tcp:8080 --wsgi myproject.app -.. _Twisted: https://twistedmatrix.com/ +.. _Twisted: https://twistedmatrix.com/trac/ .. _Twisted Web: https://twistedmatrix.com/trac/wiki/TwistedWeb .. _deploying-proxy-setups: diff --git a/docs/errorhandling.rst b/docs/errorhandling.rst index 4c260112..f985a692 100644 --- a/docs/errorhandling.rst +++ b/docs/errorhandling.rst @@ -34,10 +34,10 @@ Error Logging Tools Sending error mails, even if just for critical ones, can become overwhelming if enough users are hitting the error and log files are typically never looked at. This is why we recommend using `Sentry -`_ for dealing with application errors. It's +`_ for dealing with application errors. It's available as an Open Source project `on GitHub `__ and is also available as a `hosted version -`_ which you can try for free. Sentry +`_ which you can try for free. Sentry aggregates duplicate errors, captures the full stack trace and local variables for debugging, and sends you mails based on new errors or frequency thresholds. diff --git a/docs/extensiondev.rst b/docs/extensiondev.rst index 57d7425b..87c100fe 100644 --- a/docs/extensiondev.rst +++ b/docs/extensiondev.rst @@ -4,9 +4,8 @@ Flask Extension Development =========================== Flask, being a microframework, often requires some repetitive steps to get -a third party library working. Because very often these steps could be -abstracted to support multiple projects the `Flask Extension Registry`_ -was created. +a third party library working. Many such extensions are already available +on `PyPI `_. If you want to create your own Flask extension for something that does not exist yet, this guide to extension development will help you get your @@ -328,8 +327,8 @@ extension to be approved you have to follow these guidelines: 6. Approved extensions must define all their dependencies in the :file:`setup.py` file unless a dependency cannot be met because it is not available on PyPI. -7. The documentation must use the ``flask`` theme from the `Official - Pallets Themes`_. +7. The documentation must use the ``flask`` theme from the + `Official Pallets Themes`_. 8. The setup.py description (and thus the PyPI description) has to link to the documentation, website (if there is one) and there must be a link to automatically install the development version @@ -342,4 +341,4 @@ extension to be approved you have to follow these guidelines: .. _OAuth extension: https://pythonhosted.org/Flask-OAuth/ .. _mailinglist: http://flask.pocoo.org/mailinglist/ .. _IRC channel: http://flask.pocoo.org/community/irc/ -.. _Official Pallets Themes: https://pypi.org/project/pallets-sphinx-themes/ +.. _Official Pallets Themes: https://pypi.org/project/Pallets-Sphinx-Themes/ diff --git a/docs/htmlfaq.rst b/docs/htmlfaq.rst index 0b6ff504..faa674ff 100644 --- a/docs/htmlfaq.rst +++ b/docs/htmlfaq.rst @@ -186,7 +186,7 @@ Many other features have been added, as well. A good guide to new features in HTML5 is Mark Pilgrim's soon-to-be-published book, `Dive Into HTML5`_. Not all of them are supported in browsers yet, however, so use caution. -.. _Dive Into HTML5: http://diveintohtml5.info/ +.. _Dive Into HTML5: https://diveintohtml5.info/ What should be used? -------------------- diff --git a/docs/index.rst b/docs/index.rst index 4e80f34a..e58233b8 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -19,7 +19,7 @@ Flask depends on the `Jinja`_ template engine and the `Werkzeug`_ WSGI toolkit. The documentation for these libraries can be found at: - `Jinja documentation `_ -- `Werkzeug documentation `_ +- `Werkzeug documentation `_ .. _Jinja: https://www.palletsprojects.com/p/jinja/ .. _Werkzeug: https://www.palletsprojects.com/p/werkzeug/ diff --git a/docs/installation.rst b/docs/installation.rst index e172a1c9..7cc861f5 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -25,11 +25,11 @@ These distributions will be installed automatically when installing Flask. * `Click`_ is a framework for writing command line applications. It provides the ``flask`` command and allows adding custom management commands. -.. _Werkzeug: http://werkzeug.pocoo.org/ -.. _Jinja: http://jinja.pocoo.org/ -.. _MarkupSafe: https://pypi.org/project/MarkupSafe/ -.. _ItsDangerous: https://pythonhosted.org/itsdangerous/ -.. _Click: http://click.pocoo.org/ +.. _Werkzeug: https://palletsprojects.com/p/werkzeug/ +.. _Jinja: https://palletsprojects.com/p/jinja/ +.. _MarkupSafe: https://palletsprojects.com/p/markupsafe/ +.. _ItsDangerous: https://palletsprojects.com/p/itsdangerous/ +.. _Click: https://palletsprojects.com/p/click/ Optional dependencies ~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/patterns/appfactories.rst b/docs/patterns/appfactories.rst index 3e880205..a6d91cae 100644 --- a/docs/patterns/appfactories.rst +++ b/docs/patterns/appfactories.rst @@ -60,7 +60,7 @@ Factories & Extensions It's preferable to create your extensions and app factories so that the extension object does not initially get bound to the application. -Using `Flask-SQLAlchemy `_, +Using `Flask-SQLAlchemy `_, as an example, you should not do something along those lines:: def create_app(config_filename): @@ -93,13 +93,13 @@ To run such an application, you can use the :command:`flask` command:: export FLASK_APP=myapp flask run - -Flask will automatically detect the factory (``create_app`` or ``make_app``) + +Flask will automatically detect the factory (``create_app`` or ``make_app``) in ``myapp``. You can also pass arguments to the factory like this:: export FLASK_APP="myapp:create_app('dev')" flask run - + Then the ``create_app`` factory in ``myapp`` is called with the string ``'dev'`` as the argument. See :doc:`/cli` for more detail. diff --git a/docs/patterns/jquery.rst b/docs/patterns/jquery.rst index db27f03d..b0c0287f 100644 --- a/docs/patterns/jquery.rst +++ b/docs/patterns/jquery.rst @@ -11,7 +11,7 @@ Python primitives (numbers, strings, dicts and lists) look like which is widely supported and very easy to parse. It became popular a few years ago and quickly replaced XML as transport format in web applications. -.. _jQuery: http://jquery.com/ +.. _jQuery: https://jquery.com/ Loading jQuery -------------- @@ -27,7 +27,7 @@ to add a script statement to the bottom of your ```` to load jQuery: url_for('static', filename='jquery.js') }}"> Another method is using Google's `AJAX Libraries API -`_ to load jQuery: +`_ to load jQuery: .. sourcecode:: html diff --git a/docs/patterns/sqlalchemy.rst b/docs/patterns/sqlalchemy.rst index 831d54f0..e2dfcc5d 100644 --- a/docs/patterns/sqlalchemy.rst +++ b/docs/patterns/sqlalchemy.rst @@ -22,7 +22,7 @@ if you want to get started quickly. You can download `Flask-SQLAlchemy`_ from `PyPI `_. -.. _Flask-SQLAlchemy: http://flask-sqlalchemy.pocoo.org/ +.. _Flask-SQLAlchemy: https://flask-sqlalchemy.palletsprojects.com/ Declarative diff --git a/docs/quickstart.rst b/docs/quickstart.rst index 625f1787..ee19ea85 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -69,8 +69,8 @@ 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`. -Now head over to `http://127.0.0.1:5000/ `_, and you -should see your hello world greeting. +Now head over to http://127.0.0.1:5000/, and you should see your hello +world greeting. .. _public-server: @@ -167,7 +167,7 @@ Screenshot of the debugger in action: More information on using the debugger can be found in the `Werkzeug documentation`_. -.. _Werkzeug documentation: http://werkzeug.pocoo.org/docs/debug/#using-the-debugger +.. _Werkzeug documentation: https://werkzeug.palletsprojects.com/debug/#using-the-debugger Have another debugger in mind? See :ref:`working-with-debuggers`. @@ -384,7 +384,7 @@ package it's actually inside your package: For templates you can use the full power of Jinja2 templates. Head over to the official `Jinja2 Template Documentation -`_ for more information. +`_ for more information. Here is an example template: @@ -819,9 +819,8 @@ Here are some example log calls:: app.logger.error('An error occurred') The attached :attr:`~flask.Flask.logger` is a standard logging -:class:`~logging.Logger`, so head over to the official `logging -documentation `_ for more -information. +:class:`~logging.Logger`, so head over to the official :mod:`logging` +docs for more information. Read more on :ref:`application-errors`. diff --git a/docs/templating.rst b/docs/templating.rst index 290c0054..3fa7a066 100644 --- a/docs/templating.rst +++ b/docs/templating.rst @@ -11,7 +11,7 @@ An extension can depend on Jinja2 being present. This section only gives a very quick introduction into how Jinja2 is integrated into Flask. If you want information on the template engine's syntax itself, head over to the official `Jinja2 Template -Documentation `_ for +Documentation `_ for more information. Jinja Setup diff --git a/docs/testing.rst b/docs/testing.rst index bc9c0ea1..25275d61 100644 --- a/docs/testing.rst +++ b/docs/testing.rst @@ -20,8 +20,7 @@ framework for our tests. You can install it with ``pip``, like so:: pip install pytest -.. _pytest: - https://pytest.org +.. _pytest: https://docs.pytest.org/ The Application --------------- @@ -453,5 +452,5 @@ This is useful for testing complex validation rules and custom types. :: context = hello_command.make_context('hello', ['--name', 'flask']) assert context.params['name'] == 'FLASK' -.. _click: http://click.pocoo.org/ -.. _utilities for testing: http://click.pocoo.org/testing +.. _click: https://click.palletsprojects.com/ +.. _utilities for testing: https://click.palletsprojects.com/testing/ diff --git a/docs/tutorial/deploy.rst b/docs/tutorial/deploy.rst index a0c052ea..b6eb385e 100644 --- a/docs/tutorial/deploy.rst +++ b/docs/tutorial/deploy.rst @@ -116,6 +116,6 @@ your application. Waitress is just an example, chosen for the tutorial because it supports both Windows and Linux. There are many more WSGI servers and deployment options that you may choose for your project. -.. _Waitress: https://docs.pylonsproject.org/projects/waitress/ +.. _Waitress: https://docs.pylonsproject.org/projects/waitress/en/stable/ Continue to :doc:`next`. diff --git a/docs/tutorial/install.rst b/docs/tutorial/install.rst index 06f63dea..06c265ba 100644 --- a/docs/tutorial/install.rst +++ b/docs/tutorial/install.rst @@ -70,7 +70,7 @@ files. See the `official packaging guide`_ for another explanation of the files and options used. -.. _official packaging guide: https://packaging.python.org/tutorials/distributing-packages/ +.. _official packaging guide: https://packaging.python.org/tutorials/packaging-projects/ Install the Project diff --git a/docs/unicode.rst b/docs/unicode.rst index 3ea10a07..6e5612d2 100644 --- a/docs/unicode.rst +++ b/docs/unicode.rst @@ -6,9 +6,9 @@ text. Not only these libraries, also the majority of web related Python libraries that deal with text. If you don't know Unicode so far, you should probably read `The Absolute Minimum Every Software Developer Absolutely, Positively Must Know About Unicode and Character Sets -`_. This part of the -documentation just tries to cover the very basics so that you have a -pleasant experience with Unicode related things. +`_. +This part of the documentation just tries to cover the very basics so +that you have a pleasant experience with Unicode related things. Automatic Conversion --------------------