docs: Move Azure note to its own document.

Also, highlight note about the fact the required format of the username
field is a shorter one, update examples.

Author: ramiro

docs/azure.rst

@@ -0,0 +1,32 @@
+================================
+Connecting to Azure SQL Database
+================================
+
+Starting with version 2.1.1 pymssql can be used to connect to *Microsoft Azure
+SQL Database*.
+
+Make sure the following requirements are met:
+
+* Use FreeTDS 0.91 or newer
+* Use TDS protocol 7.1 or newer
+* Make sure FreeTDS is built with SSL support
+* Specify the database name you are connecting to in the *database* parameter of
+  the relevant ``connect()`` call
+* **IMPORTANT**: Do not use ``username@server.database.windows.net`` for the
+  *user* parameter of the relevant ``connect()`` call! You must use the shorter
+  ``username@server`` form instead!
+
+Example::
+
+    pymssql.connect("xxx.database.windows.net", "username@xxx", "password", "db_name")
+
+or, if you've defined ``myalias`` in the ``freetds.conf`` FreeTDS config file::
+
+    [myalias]
+    host = xxx.database.windows.net
+    tds version = 7.1
+    ...
+
+then you could use::
+
+    pymssql.connect("myalias", "username@xxx", "password", "db_name")

docs/index.rst

@@ -89,6 +89,7 @@ Documentation
    faq
    building_and_developing
    freetds_and_dates
+   azure
    docker
    changelog
    todo

docs/ref/_mssql.rst

@@ -113,13 +113,7 @@ Functions
         the literal shown above.
 
     .. note::
-        If you need to connect to Azure:
-
-        * Use FreeTDS 0.91 or newer (this is already a requirement of pymssql)
-        * Use TDS 7.1 or newer
-        * Make sure FreeTDS is built with SSL support
-        * Specify the database name you are connecting to in the *database* parameter
-        * Specify the username in *username@servername* form
+        If you need to connect to Azure read the relevant :doc:`topic </azure>`.
 
     .. versionadded:: 2.1.1
         The ability to connect to Azure.

docs/ref/pymssql.rst

@@ -73,28 +73,7 @@ Functions
        timeouts have a global effect.
 
    .. note::
-       If you need to connect to Azure:
-
-       * Use FreeTDS 0.91 or newer (this is already a requirement of pymssql)
-       * Use TDS 7.1 or newer
-       * Make sure FreeTDS is built with SSL support
-       * Specify the database name you are connecting to in the ``connect()`` call
-       * Specify the username in *username@servername* form in the ``connect()`` call
-
-       Example::
-
-           pymssql.connect("xxx.database.windows.net", "username@xxx.database.windows.net", "password", "db_name")
-
-       or::
-
-           pymssql.connect("myalias", "username@xxx.database.windows.net", "password", "db_name")
-
-       if you've defined ``myalias`` in the ``freetds.conf`` FreeTDS config file::
-
-           [myalias]
-           host = xxx.database.windows.net
-           tds version = 7.1
-           ...
+       If you need to connect to Azure read the relevant :doc:`topic </azure>`.
 
    .. versionadded:: 2.1.1
        The ability to connect to Azure.