Create tutorial about adding product types

docs/add_product_type.rst

@@ -0,0 +1,101 @@
+.. _add_product_type:
+
+Add a product type
+==================
+
+Add product type definition
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To add a new product type to EODag, you must add an entry to the file ``eodag/resources/product_types.yml``. Here is an example:
+
+.. code-block:: yaml
+
+    CBERS4_AWFI_L2:
+      abstract: |
+        China-Brazil Earth Resources Satellite, CBERS-4 AWFI camera Level-2 product. System corrected images, expect some
+        translation error.
+      instrument: AWFI
+      platform: CBERS
+      platformSerialIdentifier: CBERS-4
+      processingLevel: L2
+      keywords: AWFI,CBERS,CBERS-4,L2
+      sensorType: OPTICAL
+      license: proprietary
+      missionStartDate: "2014-12-07T00:00:00Z"
+      title: CBERS-4 AWFI Level-2
+
+The first line ``CBERS4_AWFI_L2:`` is a YAML key corresponding to the name by
+which the product will be referred to within EODag. Note the use of uppercase
+and underscores to separate words. This name will be used when searching for
+products of the corresponding type.
+
+The following lines need to be indented because they make a dictionary of
+configuration information for the product type we are defining. Each bit of
+information can usually be found on the provider's catalog. Note how the value
+used for the ``keywords`` entry brings together values from other entries such
+as ``instrument``, ``processingLevel``, ``platform``, etc.
+
+Add product type to a provider
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In the file ``eodag/resources/providers.yml``, add the product to the ``products``
+entry of a provider:
+
+.. code-block:: yaml
+
+    ---
+    !provider # MARK: aws_eos
+      name: aws_eos
+      # ...
+      products:
+        # ...
+        CBERS4_AWFI_L2:
+          # ...
+          # product configuration comes here
+          # ...
+
+Then for each product listed under the ``products`` entry, you may
+specify default parameters that will be used when searching for products of this
+product type:
+
+.. code-block:: yaml
+
+    ---
+    !provider
+      name: aws_eos
+      # ...
+      products:
+        # ...
+        CBERS4_AWFI_L2:
+          instrument: AWFI
+          collection: cbers4
+          processingLevel: 2
+
+With the example above, when searching for products of the type
+``CBERS4_AWFI_L2``, the search will be performed by default as if we had
+specified the instrument AWFI, the collection cbers4 and the processingLevel 2.
+Each of those parameters can be overridden when performing an actual search. Note
+that this is **not necessarily going to be sent as is** to the provider as this may be
+be further processed by a metadata mapping:
+
+.. code-block:: yaml
+
+    ---
+    !provider # MARK: aws_eos
+      name: aws_eos
+      # ...
+      products:
+        # ...
+        CBERS4_AWFI_L2:
+          # ... default eodag search parameters
+          metadata_mapping_from_product: CBERS4_PAN10M_L2
+          metadata_mapping:
+            previewBaseName: '{$.sceneID#replace_str("_L4","")}'
+            thumbnail: 'https://s3.amazonaws.com/cbers-meta-pds/{awsPath}/{previewBaseName}_small.jpeg'
+
+In the example above, we can see that the metadata mapping for the product type
+in the context of this provider can be specified in two ways:
+
+- ``metadata_mapping_from_product`` will include an existing metadata mapping
+  from another product
+- ``metadata_mapping`` will contain a metadata mapping as documented in the `section on parameters mapping <params_mapping.html>`_

docs/index.rst

@@ -130,6 +130,7 @@ Site contents
    :caption: For Developers/Contributors
 
    add_provider
+   add_product_type
    plugins
    params_mapping
    contribute