doc: document configuration options as well as how to easily migrate from Flask-RESPlus

Author: ziirish

doc/index.rst

@@ -4,19 +4,36 @@
    contain the root `toctree` directive.
 
 Welcome to Flask-RESTX's documentation!
-==========================================
+=======================================
 
 Flask-RESTX is an extension for Flask that adds support for quickly building REST APIs.
 Flask-RESTX encourages best practices with minimal setup.
 If you are familiar with Flask, Flask-RESTX should be easy to pick up.
 It provides a coherent collection of decorators and tools to describe your API
 and expose its documentation properly (using Swagger).
 
+Flask-RESTX is a community driven fork of `Flask-RESTPlus
+<https://github.com/noirbizarre/flask-restplus>`_
+
+
+Why did we fork?
+================
+
+The community has decided to fork the project due to lack of response from the
+original author @noirbizarre. We have been discussing this eventuality for
+almost `a long time <https://github.com/noirbizarre/flask-restplus/issues/593>`_.
+
+Things evolved a bit since that discussion and a few of us have been granted
+maintainers access to the github project, but only the original author has
+access rights on the PyPi project. As such, we been unable to make any actual
+releases. To prevent this project from dying out, we have forked it to continue
+development and to support our users.
+
 
 Compatibility
 =============
 
-flask-restx requires Python 2.7+.
+flask-restx requires Python 2.7+ or 3.4+.
 
 
 Installation

doc/quickstart.rst

@@ -10,6 +10,28 @@ and that you have already installed both Flask and Flask-RESTX.
 If not, then follow the steps in the :ref:`installation` section.
 
 
+Migrate from Flask-RESTPlus
+---------------------------
+
+.. warning:: The *migration* commands provided bellow are here for the illustration.
+             You may need to adapt them to properly fit your needs.
+             We also recommend you make a backup of your project prior running them.
+
+At this point, Flask-RESTX remains 100% compatible with Flask-RESTPlus' API.
+All you need to do is update your requirements to use Flask-RESTX instead of
+Flask-RESTPlus. Then you need to update all your imports.
+This can be done using something like:
+
+::
+   find . -type f -name "*.py" | xargs sed -i "s/flask_restplus/flask_restx/g"
+
+Finally, you will need to update your configuration options (described `here
+<quickstart.html#configuration>`_). Example:
+
+::
+   find . -type f -name "*.py" | xargs sed -i "s/RESTPLUS_/RESTX_/g"
+
+
 Initialization
 --------------
 
@@ -306,6 +328,48 @@ parameter to some classes or function to force order preservation:
 - globally on :class:`Namespace`: ``ns = Namespace(ordered=True)``
 - locally on :func:`marshal`: ``return marshal(data, fields, ordered=True)``
 
+Configuration
+-------------
+
+The following configuration options exist for Flask-RESTX:
+
+============================ =============== ==================================
+    OPTION                    DEFAULT VALUE             DESCRIPTION
+============================ =============== ==================================
+``BUNDLE_ERRORS``               ``False``     Bundle all the validation errors
+                                              instead of returning only the
+                                              first one encountered.
+                                              See the `Error Handling
+                                              <parsing.html#error-handling>`__
+                                              section of the documentation for
+                                              details.
+``RESTX_VALIDATE``              ``False``     Whether to enforce payload
+                                              validation by default when using
+                                              the ``@api.expect()`` decorator.
+                                              See the `@api.expect()
+                                              <swagger.html#the-api-expect-decorator>`__
+                                              documentation for details.
+``RESTX_MASK_HEADER``         ``X-Fields``    Choose the name of the *Header*
+                                              that will contain the masks to
+                                              apply to your answer.
+                                              See the `Fields masks <mask.html>`__
+                                              documentation for details.
+``RESTX_MASK_SWAGGER``          ``True``      Whether to enable the mask
+                                              documentation in your swagger or
+                                              not.
+                                              See the `mask usage
+                                              <mask.html#usage>`__ documentation
+                                              for details.
+``RESTX_INCLUDE_ALL_MODELS``     ``False``    This option allows you to include
+                                              all defined models in the generated
+                                              Swagger documentation, even if they
+                                              are not explicitly used in either
+                                              ``expect`` nor ``marshal_with``
+                                              decorators.
+``RESTX_JSON``                   ``{}``       Dictionary of options to pass to
+                                              the json *serializer* (by default
+                                              ``json.dumps``).
+============================ =============== ==================================
 
 Full example
 ------------