update project metadata

new readme
readme as setup.py long_description
links in changes
git in authors
add travis osx env
break out docs build in travis
remove python_requires for now

.gitattributes

@@ -1 +1 @@
-CHANGES merge=union
+CHANGES.rst merge=union

.travis.yml

@@ -4,7 +4,9 @@ language: python
 matrix:
   include:
     - python: 3.6
-      env: TOXENV=py,simplejson,devel,lowest,codecov,docs-html
+      env: TOXENV=py,simplejson,devel,lowest,codecov
+    - python: 3.6
+      env: TOXENV=docs-html
     - python: 3.5
       env: TOXENV=py,codecov
     - python: 3.4
@@ -15,9 +17,16 @@ matrix:
       env: TOXENV=py,codecov
     - python: nightly
       env: TOXENV=py
+    - os: osx
+      language: generic
+      env: TOXENV=py
   allow_failures:
     - python: nightly
       env: TOXENV=py
+    - os: osx
+      language: generic
+      env: TOXENV=py
+  fast_finish: true
 
 install:
   - pip install tox

AUTHORS

@@ -1,40 +1,12 @@
-Flask is written and maintained by Armin Ronacher and
-various contributors:
+Flask is developed and maintained by the Pallets team and community
+contributors. It was created by Armin Ronacher. The core maintainers
+are:
 
-Development Lead
-````````````````
+- David Lord (davidism)
+- Adrian Mönnich (ThiefMaster)
+- Armin Ronacher (mitsuhiko)
+- Marcus Unterwaditzer (untitaker)
 
-- Armin Ronacher <[email protected]>
+A full list of contributors is available from git with::
 
-Patches and Suggestions
-```````````````````````
-
-- Adam Byrtek
-- Adam Zapletal
-- Ali Afshar
-- Chris Edgemon
-- Chris Grindstaff
-- Christopher Grebs
-- Daniel Neuhäuser
-- Dan Sully
-- David Lord @davidism
-- Edmond Burnett
-- Florent Xicluna
-- Georg Brandl
-- Hsiaoming Yang @lepture
-- Jeff Widman @jeffwidman
-- Joshua Bronson @jab
-- Justin Quick
-- Kenneth Reitz
-- Keyan Pishdadian
-- Marian Sigler
-- Martijn Pieters
-- Matt Campell
-- Matthew Frazier
-- Michael van Tellingen
-- Ron DuPlain
-- Sebastien Estienne
-- Simon Sapin
-- Stephane Wirtel
-- Thomas Schranz
-- Zhao Xiaohong
+    git shortlog -sne

CHANGES.rst

@@ -1,3 +1,5 @@
+.. currentmodule:: flask
+
 Flask Changelog
 ===============
 
@@ -11,114 +13,126 @@ unreleased
 - Bump minimum dependency versions to the latest stable versions:
   Werkzeug >= 0.14, Jinja >= 2.10, itsdangerous >= 0.24, Click >= 5.1.
   (`#2586`_)
-- Make ``app.run()`` into a noop if a Flask application is run from the
-  development server on the command line. This avoids some behavior that
-  was confusing to debug for newcomers.
-- Change default configuration ``JSONIFY_PRETTYPRINT_REGULAR=False``.
-  ``jsonify()`` method returns compressed response by default, and pretty
-  response in debug mode. (`#2193`_)
-- Change ``Flask.__init__`` to accept two new keyword arguments,
-  ``host_matching`` and ``static_host``. This enables ``host_matching`` to be
-  set properly by the time the constructor adds the static route, and enables
-  the static route to be properly associated with the required host.
-  (``#1559``)
-- ``send_file`` supports Unicode in ``attachment_filename``. (`#2223`_)
-- Pass ``_scheme`` argument from ``url_for`` to ``handle_build_error``.
-  (`#2017`_)
-- Add support for ``provide_automatic_options`` in ``add_url_rule`` to disable
-  adding OPTIONS method when the ``view_func`` argument is not a class.
-  (`#1489`_).
-- ``MethodView`` can inherit method handlers from base classes. (`#1936`_)
-- Errors caused while opening the session at the beginning of the request are
-  handled by the app's error handlers. (`#2254`_)
-- Blueprints gained ``json_encoder`` and ``json_decoder`` attributes to
-  override the app's encoder and decoder. (`#1898`_)
-- ``Flask.make_response`` raises ``TypeError`` instead of ``ValueError`` for
-  bad response types. The error messages have been improved to describe why the
-  type is invalid. (`#2256`_)
-- Add ``routes`` CLI command to output routes registered on the application.
-  (`#2259`_)
+- Skip :meth:`app.run <Flask.run>` when a Flask application is run from
+  the command line. This avoids some behavior that was confusing to
+  debug.
+- Change the default for :data:`JSONIFY_PRETTYPRINT_REGULAR` to
+  ``False``. :func:`~json.jsonify` returns a compact format by default,
+  and an indented format in debug mode. (`#2193`_)
+- :meth:`Flask.__init__ <Flask>` accepts the ``host_matching`` argument
+  and sets it on :attr:`~Flask.url_map`. (`#1559`_)
+- :meth:`Flask.__init__ <Flask>` accepts the ``static_host`` argument
+  and passes it as the ``host`` argument when defining the static route.
+  (`#1559`_)
+- :func:`send_file` supports Unicode in ``attachment_filename``.
+  (`#2223`_)
+- Pass ``_scheme`` argument from :func:`url_for` to
+  :meth:`~Flask.handle_url_build_error`. (`#2017`_)
+- :meth:`~Flask.add_url_rule` accepts the ``provide_automatic_options``
+  argument to disable adding the ``OPTIONS`` method. (`#1489`_)
+- :class:`~views.MethodView` subclasses inherit method handlers from
+  base classes. (`#1936`_)
+- Errors caused while opening the session at the beginning of the
+  request are handled by the app's error handlers. (`#2254`_)
+- Blueprints gained :attr:`~Blueprint.json_encoder` and
+  :attr:`~Blueprint.json_decoder` attributes to override the app's
+  encoder and decoder. (`#1898`_)
+- :meth:`Flask.make_response` raises ``TypeError`` instead of
+  ``ValueError`` for bad response types. The error messages have been
+  improved to describe why the type is invalid. (`#2256`_)
+- Add ``routes`` CLI command to output routes registered on the
+  application. (`#2259`_)
 - Show warning when session cookie domain is a bare hostname or an IP
-  address, as these may not behave properly in some browsers, such as Chrome.
-  (`#2282`_)
+  address, as these may not behave properly in some browsers, such as
+  Chrome. (`#2282`_)
 - Allow IP address as exact session cookie domain. (`#2282`_)
-- ``SESSION_COOKIE_DOMAIN`` is set if it is detected through ``SERVER_NAME``.
-  (`#2282`_)
-- Auto-detect zero-argument app factory called ``create_app`` or ``make_app``
-  from ``FLASK_APP``. (`#2297`_)
-- Factory functions are not required to take a ``script_info`` parameter to
-  work with the ``flask`` command. If they take a single parameter or a
-  parameter named ``script_info``, the ``ScriptInfo`` object will be passed.
-  (`#2319`_)
-- FLASK_APP=myproject.app:create_app('dev') support.
-- ``FLASK_APP`` can be set to an app factory, with arguments if needed, for
-  example ``FLASK_APP=myproject.app:create_app('dev')``. (`#2326`_)
-- ``FLASK_APP`` can point to local packages that are not installed in dev mode,
-  although `pip install -e` should still be preferred. (`#2414`_)
-- ``View.provide_automatic_options = True`` is set on the view function from
-  ``View.as_view``, to be detected in ``app.add_url_rule``. (`#2316`_)
+- ``SESSION_COOKIE_DOMAIN`` is set if it is detected through
+  ``SERVER_NAME``. (`#2282`_)
+- Auto-detect zero-argument app factory called ``create_app`` or
+  ``make_app`` from ``FLASK_APP``. (`#2297`_)
+- Factory functions are not required to take a ``script_info`` parameter
+  to work with the ``flask`` command. If they take a single parameter or
+  a parameter named ``script_info``, the :class:`~cli.ScriptInfo` object
+  will be passed. (`#2319`_)
+- ``FLASK_APP`` can be set to an app factory, with arguments if needed,
+  for example ``FLASK_APP=myproject.app:create_app('dev')``. (`#2326`_)
+- ``FLASK_APP`` can point to local packages that are not installed in
+  editable mode, although ``pip install -e`` is still preferred.
+  (`#2414`_)
+- The :class:`~views.View` class attribute
+  :attr:`~views.View.provide_automatic_options` is set in
+  :meth:`~views.View.as_view`, to be detected by
+  :meth:`~Flask.add_url_rule`. (`#2316`_)
 - Error handling will try handlers registered for ``blueprint, code``,
-  ``app, code``, ``blueprint, exception``, ``app, exception``. (`#2314`_)
-- ``Cookie`` is added to the response's ``Vary`` header if the session is
-  accessed at all during the request (and it wasn't deleted). (`#2288`_)
-- ``app.test_request_context()`` take ``subdomain`` and ``url_scheme``
-  parameters for use when building base URL. (`#1621`_)
-- Set ``APPLICATION_ROOT = '/'`` by default. This was already the implicit
-  default when it was set to ``None``.
-- ``TRAP_BAD_REQUEST_ERRORS`` is enabled by default in debug mode.
-  ``BadRequestKeyError`` has a message with the bad key in debug mode instead
-  of the generic bad request message. (`#2348`_)
-- Allow registering new tags with ``TaggedJSONSerializer`` to support
-  storing other types in the session cookie. (`#2352`_)
-- Only open the session if the request has not been pushed onto the context
-  stack yet. This allows ``stream_with_context`` generators to access the same
-  session that the containing view uses. (`#2354`_)
-- Add ``json`` keyword argument for the test client request methods. This will
-  dump the given object as JSON and set the appropriate content type.
-  (`#2358`_)
-- Extract JSON handling to a mixin applied to both the request and response
-  classes used by Flask. This adds the ``is_json`` and ``get_json`` methods to
-  the response to make testing JSON response much easier. (`#2358`_)
-- Removed error handler caching because it caused unexpected results for some
-  exception inheritance hierarchies. Register handlers explicitly for each
-  exception if you don't want to traverse the MRO. (`#2362`_)
+  ``app, code``, ``blueprint, exception``, ``app, exception``.
+  (`#2314`_)
+- ``Cookie`` is added to the response's ``Vary`` header if the session
+  is accessed at all during the request (and not deleted). (`#2288`_)
+- :meth:`~Flask.test_request_context` accepts ``subdomain`` and
+  ``url_scheme`` arguments for use when building the base URL.
+  (`#1621`_)
+- Set :data:`APPLICATION_ROOT` to ``'/'`` by default. This was already
+  the implicit default when it was set to ``None``.
+- :data:`TRAP_BAD_REQUEST_ERRORS` is enabled by default in debug mode.
+  ``BadRequestKeyError`` has a message with the bad key in debug mode
+  instead of the generic bad request message. (`#2348`_)
+- Allow registering new tags with
+  :class:`~json.tag.TaggedJSONSerializer` to support storing other types
+  in the session cookie. (`#2352`_)
+- Only open the session if the request has not been pushed onto the
+  context stack yet. This allows :func:`~stream_with_context`
+  generators to access the same session that the containing view uses.
+  (`#2354`_)
+- Add ``json`` keyword argument for the test client request methods.
+  This will dump the given object as JSON and set the appropriate
+  content type. (`#2358`_)
+- Extract JSON handling to a mixin applied to both the :class:`Request`
+  and :class:`Response` classes. This adds the :meth:`~Response.is_json`
+  and :meth:`~Response.get_json` methods to the response to make testing
+  JSON response much easier. (`#2358`_)
+- Removed error handler caching because it caused unexpected results for
+  some exception inheritance hierarchies. Register handlers explicitly
+  for each exception if you want to avoid traversing the MRO. (`#2362`_)
 - Fix incorrect JSON encoding of aware, non-UTC datetimes. (`#2374`_)
-- Template auto reloading will honor the ``run`` command's ``debug`` flag even
-  if ``app.jinja_env`` was already accessed. (`#2373`_)
+- Template auto reloading will honor debug mode even even if
+  :attr:`~Flask.jinja_env` was already accessed. (`#2373`_)
 - The following old deprecated code was removed. (`#2385`_)
 
   - ``flask.ext`` - import extensions directly by their name instead of
     through the ``flask.ext`` namespace. For example,
     ``import flask.ext.sqlalchemy`` becomes ``import flask_sqlalchemy``.
-  - ``Flask.init_jinja_globals`` - extend ``Flask.create_jinja_environment``
-    instead.
-  - ``Flask.error_handlers`` - tracked by ``Flask.error_handler_spec``,
-    use ``@app.errorhandler`` to register handlers.
-  - ``Flask.request_globals_class`` - use ``Flask.app_ctx_globals_class``
-    instead.
-  - ``Flask.static_path`` - use ``Flask.static_url_path`` instead.
-  - ``Request.module`` - use ``Request.blueprint`` instead.
-
-- The ``request.json`` property is no longer deprecated. (`#1421`_)
-- Support passing an existing ``EnvironBuilder`` or ``dict`` to
-  ``test_client.open``. (`#2412`_)
-- The ``flask`` command and ``app.run`` will load environment variables using
-  from ``.env`` and ``.flaskenv`` files if python-dotenv is installed.
-  (`#2416`_)
-- When passing a full URL to the test client, use the scheme in the URL instead
-  of the ``PREFERRED_URL_SCHEME``. (`#2430`_)
-- ``app.logger`` has been simplified. ``LOGGER_NAME`` and
-  ``LOGGER_HANDLER_POLICY`` config was removed. The logger is always named
-  ``flask.app``. The level is only set on first access, it doesn't check
-  ``app.debug`` each time. Only one format is used, not different ones
-  depending on ``app.debug``. No handlers are removed, and a handler is only
-  added if no handlers are already configured. (`#2436`_)
-- Blueprint view function name may not contain dots. (`#2450`_)
-- Fix a ``ValueError`` caused by invalid Range requests in some cases.
-  (`#2526`_)
-- The dev server now uses threads by default. (`#2529`_)
-- Loading config files with ``silent=True`` will ignore ``ENOTDIR``
-  errors. (`#2581`_)
+  - ``Flask.init_jinja_globals`` - extend
+    :meth:`Flask.create_jinja_environment` instead.
+  - ``Flask.error_handlers`` - tracked by
+    :attr:`Flask.error_handler_spec`, use :meth:`Flask.errorhandler` to
+    register handlers.
+  - ``Flask.request_globals_class`` - use
+    :attr:`Flask.app_ctx_globals_class` instead.
+  - ``Flask.static_path`` - use :attr:`Flask.static_url_path` instead.
+  - ``Request.module`` - use :attr:`Request.blueprint` instead.
+
+- The :attr:`Request.json` property is no longer deprecated. (`#1421`_)
+- Support passing a :class:`~werkzeug.test.EnvironBuilder` or
+  ``dict`` to :meth:`test_client.open <werkzeug.test.Client.open>`.
+  (`#2412`_)
+- The ``flask`` command and :meth:`Flask.run` will load environment
+  variables from ``.env`` and ``.flaskenv`` files if python-dotenv is
+  installed. (`#2416`_)
+- When passing a full URL to the test client, the scheme in the URL is
+  used instead of :data:`PREFERRED_URL_SCHEME`. (`#2430`_)
+- :attr:`Flask.logger` has been simplified. ``LOGGER_NAME`` and
+  ``LOGGER_HANDLER_POLICY`` config was removed. The logger is always
+  named ``flask.app``. The level is only set on first access, it doesn't
+  check :attr:`Flask.debug` each time. Only one format is used, not
+  different ones depending on :attr:`Flask.debug`. No handlers are
+  removed, and a handler is only added if no handlers are already
+  configured. (`#2436`_)
+- Blueprint view function names may not contain dots. (`#2450`_)
+- Fix a ``ValueError`` caused by invalid ``Range`` requests in some
+  cases. (`#2526`_)
+- The development server uses threads by default. (`#2529`_)
+- Loading config files with ``silent=True`` will ignore
+  :data:`~errno.ENOTDIR` errors. (`#2581`_)
 - Pass ``--cert`` and ``--key`` options to ``flask run`` to run the
   development server over HTTPS. (`#2606`_)
 - Added :data:`SESSION_COOKIE_SAMESITE` to control the ``SameSite``
@@ -127,6 +141,7 @@ unreleased
 .. _pallets/meta#24: https://github.com/pallets/meta/issues/24
 .. _#1421: https://github.com/pallets/flask/issues/1421
 .. _#1489: https://github.com/pallets/flask/pull/1489
+.. _#1559: https://github.com/pallets/flask/issues/1559
 .. _#1621: https://github.com/pallets/flask/pull/1621
 .. _#1898: https://github.com/pallets/flask/pull/1898
 .. _#1936: https://github.com/pallets/flask/pull/1936

CONTRIBUTING.rst

@@ -131,8 +131,22 @@ Read more about `coverage <https://coverage.readthedocs.io>`_.
 Running the full test suite with ``tox`` will combine the coverage reports
 from all runs.
 
-``make`` targets
-~~~~~~~~~~~~~~~~
+
+Building the docs
+~~~~~~~~~~~~~~~~~
+
+Build the docs in the ``docs`` directory using Sphinx::
+
+    cd docs
+    make html
+
+Open ``_build/html/index.html`` in your browser to view the docs.
+
+Read more about `Sphinx <http://www.sphinx-doc.org>`_.
+
+
+make targets
+~~~~~~~~~~~~
 
 Flask provides a ``Makefile`` with various shortcuts. They will ensure that
 all dependencies are installed.