Changes in docs [Form Recognizer] (#12216)

* initial commit

* one more change

* readme

* Apply suggestions from code review

* Update sdk/formrecognizer/azure-ai-formrecognizer/README.md

* Update sdk/formrecognizer/azure-ai-formrecognizer/azure/ai/formrecognizer/_form_training_client.py

* Update sdk/formrecognizer/azure-ai-formrecognizer/azure/ai/formrecognizer/_form_training_client.py

* comments

Author: rakshith91

sdk/formrecognizer/azure-ai-formrecognizer/README.md

@@ -184,6 +184,16 @@ for recognized_form in result:
         ))
 ```
 
+Alternatively, a form url can also be used to recognize custom forms using the `begin_recognize_custom_forms_from_url` method. The `_from_url` methods exist for
+all the recognize methods.
+
+
+```
+form_url_jpg = "<url_of_the_form>"
+poller = form_recognizer_client.begin_recognize_custom_forms_from_url(model_id=model_id, form_url=form_url)
+result = poller.result()
+```
+
 ### Recognize Content
 Recognize text and table structures, along with their bounding box coordinates, from documents.
 
@@ -323,6 +333,14 @@ except ResourceNotFoundError:
     print("Successfully deleted model with id {}".format(custom_model.model_id))
 ```
 
+## Async APIs
+This library also includes a complete async API supported on Python 3.5+. To use it, you must
+first install an async transport, such as [aiohttp](https://pypi.org/project/aiohttp/).
+See
+[azure-core documentation](https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/core/azure-core/README.md#transport)
+for more information.
+
+
 ## Optional Configuration
 
 Optional keyword arguments can be passed in at the client and per-operation level.
@@ -407,6 +425,7 @@ This project has adopted the [Microsoft Open Source Code of Conduct][code_of_con
 [python-fr-product-docs]: https://docs.microsoft.com/azure/cognitive-services/form-recognizer/overview
 [python-fr-ref-docs]: https://aka.ms/azsdk/python/formrecognizer/docs
 [python-fr-samples]: https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/formrecognizer/azure-ai-formrecognizer/samples
+[train-a-model-using-labeled-data]: https://docs.microsoft.com/azure/cognitive-services/form-recognizer/quickstarts/python-labeled-data#train-a-model-using-labeled-data
 
 
 [quickstart_training]: https://docs.microsoft.com/azure/cognitive-services/form-recognizer/quickstarts/curl-train-extract#train-a-form-recognizer-model

sdk/formrecognizer/azure-ai-formrecognizer/azure/ai/formrecognizer/_form_training_client.py

@@ -93,11 +93,13 @@ def __init__(self, endpoint, credential, **kwargs):
     def begin_training(self, training_files_url, use_training_labels, **kwargs):
         # type: (str, bool, Any) -> LROPoller[CustomFormModel]
         """Create and train a custom model. The request must include a `training_files_url` parameter that is an
-        externally accessible Azure storage blob container Uri (preferably a Shared Access Signature Uri).
+        externally accessible Azure storage blob container Uri (preferably a Shared Access Signature Uri). Note that
+        a container uri is accepted only when the container is public.
         Models are trained using documents that are of the following content type - 'application/pdf',
         'image/jpeg', 'image/png', 'image/tiff'. Other type of content in the container is ignored.
 
-        :param str training_files_url: An Azure Storage blob container's SAS URI.
+        :param str training_files_url: An Azure Storage blob container's SAS URI. A container uri can be used if the
+            container is public.
         :param bool use_training_labels: Whether to train with labels or not. Corresponding labeled files must
             exist in the blob container.
         :keyword str prefix: A case-sensitive prefix string to filter documents in the source path for
@@ -278,7 +280,9 @@ def get_copy_authorization(self, resource_id, resource_region, **kwargs):
         :param str resource_id: Azure Resource Id of the target Form Recognizer resource
             where the model will be copied to.
         :param str resource_region: Location of the target Form Recognizer resource. A valid Azure
-            region name supported by Cognitive Services.
+            region name supported by Cognitive Services. For example, 'westus', 'eastus' etc.
+            See https://azure.microsoft.com/global-infrastructure/services/?products=cognitive-services
+            for the regional availability of Cognitive Services
         :return: A dictionary with values for the copy authorization -
             "modelId", "accessToken", "resourceId", "resourceRegion", and "expirationDateTimeTicks".
         :rtype: Dict[str, Union[str, int]]

sdk/formrecognizer/azure-ai-formrecognizer/azure/ai/formrecognizer/_models.py

@@ -250,7 +250,8 @@ class FieldText(FormContent):
         Units are in pixels for images and inches for PDF.
     :ivar text_content:
         When `include_text_content` is set to true, a list of text
-        elements constituting this field or value is returned.
+        elements constituting this field or value is returned. The list
+        constitutes of text elements such as lines and words.
     :vartype text_content: list[~azure.ai.formrecognizer.FormWord, ~azure.ai.formrecognizer.FormLine]
     """
 
@@ -472,7 +473,8 @@ class FormTableCell(FormContent):
         The 1-based number of the page in which this content is present.
     :ivar text_content:
         When `include_text_content` is set to true, a list of text
-        elements constituting this cell is returned.
+        elements constituting this cell is returned. The list
+        constitutes of text elements such as lines and words.
         For calls to recognize content, this list is always populated.
     :vartype text_content: list[~azure.ai.formrecognizer.FormWord, ~azure.ai.formrecognizer.FormLine]
     """

sdk/formrecognizer/azure-ai-formrecognizer/azure/ai/formrecognizer/aio/_form_training_client_async.py

@@ -102,11 +102,13 @@ async def begin_training(
             **kwargs: Any
     ) -> AsyncLROPoller[CustomFormModel]:
         """Create and train a custom model. The request must include a `training_files_url` parameter that is an
-        externally accessible Azure storage blob container Uri (preferably a Shared Access Signature Uri).
+        externally accessible Azure storage blob container Uri (preferably a Shared Access Signature Uri). Note that
+        a container uri is accepted only when the container is public.
         Models are trained using documents that are of the following content type - 'application/pdf',
         'image/jpeg', 'image/png', 'image/tiff'. Other type of content in the container is ignored.
 
-        :param str training_files_url: An Azure Storage blob container's SAS URI.
+        :param str training_files_url: An Azure Storage blob container's SAS URI. A container uri can be used if the
+            container is public.
         :param bool use_training_labels: Whether to train with labels or not. Corresponding labeled files must
             exist in the blob container.
         :keyword str prefix: A case-sensitive prefix string to filter documents in the source path for
@@ -300,7 +302,9 @@ async def get_copy_authorization(
         :param str resource_id: Azure Resource Id of the target Form Recognizer resource
             where the model will be copied to.
         :param str resource_region: Location of the target Form Recognizer resource. A valid Azure
-            region name supported by Cognitive Services.
+            region name supported by Cognitive Services. For example, 'westus', 'eastus' etc.
+            See https://azure.microsoft.com/global-infrastructure/services/?products=cognitive-services
+            for the regional availability of Cognitive Services
         :return: A dictionary with values for the copy authorization -
             "modelId", "accessToken", "resourceId", "resourceRegion", and "expirationDateTimeTicks".
         :rtype: Dict[str, Union[str, int]]

sdk/formrecognizer/azure-ai-formrecognizer/samples/async_samples/sample_copy_model_async.py

@@ -11,7 +11,8 @@
 
 DESCRIPTION:
     This sample demonstrates how to copy a custom model from a source Form Recognizer resource
-    to a target Form Recognizer resource.
+    to a target Form Recognizer resource. The resource id and the resource region can be found
+    in the azure portal.
 
 USAGE:
     python sample_copy_model_async.py

sdk/formrecognizer/azure-ai-formrecognizer/samples/sample_copy_model.py

@@ -11,7 +11,8 @@
 
 DESCRIPTION:
     This sample demonstrates how to copy a custom model from a source Form Recognizer resource
-    to a target Form Recognizer resource.
+    to a target Form Recognizer resource. The resource id and the resource region can be found
+    in the azure portal.
 
 USAGE:
     python sample_copy_model.py