Merge pull request #106 from corydolphin/patch/docs

Update documentation to use new travis link

README.md

@@ -67,6 +67,10 @@ import logging
 logging.basicConfig(level=logging.DEBUG)
 ```
 
+## Documentation
+
+For a full list of options, please see the full [documentation](http://flask-cors.readthedocs.org/en/latest/)
+
 ### Options
 
 #### origins
@@ -144,12 +148,6 @@ When using JSON cross origin, browsers will issue a pre-flight OPTIONS request f
 app.config['CORS_HEADERS'] = 'Content-Type'
 ```
 
-
-## Documentation
-
-For a full list of options, please see the full [documentation](http://flask-cors.readthedocs.org/en/latest/)
-
-
 ## Tests
 
 A simple set of tests is included in `test/`. To run, install nose, and simply invoke `nosetests` or `python setup.py test` to exercise the tests.

README.rst

@@ -91,6 +91,12 @@ documentation <http://flask.pocoo.org/docs/0.10/errorhandling/>`__.
     # make your awesome app
     logging.basicConfig(level=logging.DEBUG)
 
+Documentation
+-------------
+
+For a full list of options, please see the full
+`documentation <http://flask-cors.readthedocs.org/en/latest/>`__
+
 Options
 ~~~~~~~
 
@@ -217,12 +223,6 @@ value on your application, e.g:
 
     app.config['CORS_HEADERS'] = 'Content-Type'
 
-Documentation
--------------
-
-For a full list of options, please see the full
-`documentation <http://flask-cors.readthedocs.org/en/latest/>`__
-
 Tests
 -----
 

docs/index.rst

@@ -7,14 +7,6 @@ Flask-CORS
 A Flask extension for handling Cross Origin Resource Sharing (CORS),
 making cross-origin AJAX possible.
 
-Contact
--------
-
-Questions, comments or improvements? Please create an issue on
-`Github <https://github.com/wcdolphin/flask-cors>`__, tweet at
-`@wcdolphin <https://twitter.com/wcdolphin>`__ or send me an email.
-
-
 Installation
 ------------
 
@@ -28,9 +20,13 @@ Usage
 -----
 
 This extension enables CORS support either via a decorator, or a Flask
-extension. This extension enables CORS support either via a decorator, or a Flask
-extension. There are three examples shown in the examples directory, showing
-the major use cases.
+extension. There are three examples shown in the
+`examples <https://github.com/corydolphin/flask-cors/tree/master/examples>`__
+directory, showing the major use cases. The suggested configuration is
+the
+`simple\_example.py <https://github.com/corydolphin/flask-cors/tree/master/examples/simple_example.py>`__,
+or the
+`app\_example.py <https://github.com/corydolphin/flask-cors/tree/master/examples/app_based_example.py>`__.
 
 Simple Usage
 ~~~~~~~~~~~~
@@ -51,8 +47,8 @@ arguments in order to allow CORS on all routes.
 Resource specific CORS
 ^^^^^^^^^^^^^^^^^^^^^^
 
-Alternatively, a list of resources and associated settings for CORS
-can be supplied, selectively enables CORS support on a set of paths on your
+Alternatively, a list of resources and associated settings for CORS can
+be supplied, selectively enables CORS support on a set of paths on your
 app.
 
 Note: this resources parameter can also be set in your application's
@@ -70,12 +66,10 @@ config.
 Route specific CORS via decorator
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-This extension also exposes a simple decorator to decorate flask
-routes with.
-Simply add ``@cross_origin()`` below a call to Flask's
-``@app.route(..)``
-incanation to accept the default options and allow CORS on a given
-route.
+This extension also exposes a simple decorator to decorate flask routes
+with. Simply add ``@cross_origin()`` below a call to Flask's
+``@app.route(..)`` incanation to accept the default options and allow
+CORS on a given route.
 
 .. code:: python
 
@@ -84,37 +78,150 @@ route.
     def helloWorld():
       return "Hello, cross-origin-world!"
 
-Using JSON with CORS
-~~~~~~~~~~~~~~~~~~~~
+Logging
+^^^^^^^
 
-When using JSON cross origin, browsers will issue a pre-flight OPTIONS
-request for POST requests. In order for browsers to allow POST requests with a
-JSON content type, you must allow the Content-Type header. The simplest way
-to do this is to simply set the CORS\_HEADERS configuration value on your
-application:
-e.g.
+Flask-Cors uses standard Python logging, using the module name
+'Flask-Cors'. You can read more about logging from `Flask's
+documentation <http://flask.pocoo.org/docs/0.10/errorhandling/>`__.
 
 .. code:: python
 
-    app.config['CORS_HEADERS'] = 'Content-Type'
+    import logging
+    # make your awesome app
+    logging.basicConfig(level=logging.DEBUG)
 
-Logging
+Documentation
+-------------
+
+For a full list of options, please see the full
+`documentation <http://flask-cors.readthedocs.org/en/latest/>`__
+
+Options
+~~~~~~~
+
+origins
 ^^^^^^^
 
-Flask-Cors uses standard Python logging, using the module name
-'Flask-Cors'. You can read more about logging from `Flask's
-documentation <http://flask.pocoo.org/docs/0.10/errorhandling/>`__. To
-add logging for flask\_cors to the standard StreamHandler:
+    Default : '\*'
+
+The origin, or list of origins to allow requests from. The origin(s) may
+be regular expressions, exact origins, or else an asterisk.
+
+methods
+^^^^^^^
+
+    Default : [GET, HEAD, POST, OPTIONS, PUT, PATCH, DELETE]
+
+The method or list of methods which the allowed origins are allowed to
+access for non-simple requests.
+
+expose\_headers
+^^^^^^^^^^^^^^^
+
+    Default : None
+
+The header or list of headers which are safe to expose to the API of a
+CORS API specification
+
+allow\_headers
+^^^^^^^^^^^^^^
+
+    Default : None
+
+The header or list of header field names which can be used when this
+resource is accessed by allowed origins.
+
+supports\_credentials
+^^^^^^^^^^^^^^^^^^^^^
+
+    Default : False
+
+Allows users to make authenticated requests. If true, injects the
+``Access-Control-Allow-Credentials`` header in responses.
+
+max\_age
+^^^^^^^^
+
+    Default : None
+
+The maximum time for which this CORS request maybe cached. This value is
+set as the ``Access-Control-Max-Age`` header.
+
+send\_wildcard
+^^^^^^^^^^^^^^
+
+    Default : True
+
+If True, and the origins parameter is ``*``, a wildcard
+``Access-Control-Allow-Origin`` header is sent, rather than the
+request's ``Origin`` header.
+
+always\_send
+^^^^^^^^^^^^
+
+    Default : True
+
+If True, CORS headers are sent even if there is no ``Origin`` in the
+request's headers.
+
+automatic\_options
+^^^^^^^^^^^^^^^^^^
+
+    Default : True
+
+If True, CORS headers will be returned for OPTIONS requests. For use
+with cross domain POST requests which preflight OPTIONS requests, you
+will need to specifically allow the Content-Type header. \*\* Only
+applicable for use in the decorator\*\*
+
+vary\_header
+^^^^^^^^^^^^
+
+    Default : True
+
+If True, the header Vary: Origin will be returned as per suggestion by
+the W3 implementation guidelines. Setting this header when the
+``Access-Control-Allow-Origin`` is dynamically generated (e.g. when
+there is more than one allowed origin, and an Origin than '\*' is
+returned) informs CDNs and other caches that the CORS headers are
+dynamic, and cannot be re-used. If False, the Vary header will never be
+injected or altered.
+
+Application-wide options
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Alternatively, you can set all parameters **except automatic\_options**
+in an app's config object. Setting these at the application level
+effectively changes the default value for your application, while still
+allowing you to override it on a per-resource basis, either via the CORS
+Flask-Extension and regular expressions, or via the ``@cross_origin()``
+decorator.
+
+The application-wide configuration options are identical to the keyword
+arguments to ``cross_origin``, creatively prefixed with ``CORS_``
+
+-  CORS\_ORIGINS
+-  CORS\_METHODS
+-  CORS\_HEADERS
+-  CORS\_EXPOSE\_HEADERS
+-  CORS\_ALWAYS\_SEND
+-  CORS\_MAX\_AGE
+-  CORS\_SEND\_WILDCARD
+-  CORS\_ALWAYS\_SEND
+
+Using JSON with CORS
+~~~~~~~~~~~~~~~~~~~~
+
+When using JSON cross origin, browsers will issue a pre-flight OPTIONS
+request for POST requests. In order for browsers to allow POST requests
+with a JSON content type, you must allow the Content-Type header. The
+simplest way to do this is to simply set the CORS\_HEADERS configuration
+value on your application, e.g:
 
 .. code:: python
 
-    for logger in (app.logger, logging.getLogger('Flask-Cors')):
-        sh = logging.StreamHandler()
-        sh.setFormatter(
-            logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
-        )
-        logger.addHandler(sh)
-        logger.setLevel(logging.DEBUG)
+    app.config['CORS_HEADERS'] = 'Content-Type'
 
 
 Full description of options
@@ -143,9 +250,29 @@ a particular view.
 .. literalinclude:: ../examples/view_based_example.py
    :language: python
 
+Tests
+-----
+
+A simple set of tests is included in ``test/``. To run, install nose,
+and simply invoke ``nosetests`` or ``python setup.py test`` to exercise
+the tests.
+
+Contributing
+------------
+
+Questions, comments or improvements? Please create an issue on
+`Github <https://github.com/corydolphin/flask-cors>`__, tweet at
+`@corydolphin <https://twitter.com/corydolphin>`__ or send me an email.
+
+Credits
+-------
+
+This Flask extension is based upon the `Decorator for the HTTP Access
+Control <http://flask.pocoo.org/snippets/56/>`__ written by Armin
+Ronacher.
 
-.. |Build Status| image:: https://api.travis-ci.org/CoryDolphin/flask-cors.png?branch=master
-   :target: https://travis-ci.org/CoryDolphin/flask-cors
+.. |Build Status| image:: https://api.travis-ci.org/corydolphin/flask-cors.svg?branch=master
+   :target: https://travis-ci.org/corydolphin/flask-cors
 .. |Latest Version| image:: https://pypip.in/version/Flask-Cors/badge.svg
    :target: https://pypi.python.org/pypi/Flask-Cors/
 .. |Downloads| image:: https://pypip.in/download/Flask-Cors/badge.svg