doc: shields: Update shields doc with board overriding and variants

Shields subsystem provides the possibility to override configuration
for boards and to define variants.

Reflect this in documentation.

Signed-off-by: Erwan Gouriou <erwan.gouriou@linaro.org>

doc/guides/porting/board_porting.rst

@@ -121,6 +121,8 @@ A board implements an SoC with all its features, together with peripherals
 available on the board that differentiates the board with additional interfaces
 and features not available in the SoC.
 
+.. _default_board_configuration:
+
 Default board configuration
 ***************************
 

doc/guides/porting/shields.rst

@@ -18,6 +18,7 @@ under :zephyr_file:`/boards/shields`:
 
    boards/shields/<shield>
    ├── <shield>.overlay
+   ├── <shield>.conf
    └── dts_fixup.h
 
 These files provides shield configuration as follows:
@@ -26,6 +27,11 @@ These files provides shield configuration as follows:
   format that is merged with the board's device tree information before
   compilation.
 
+* **<shield>.conf**: This file defines values for Kconfig symbols that are
+  required for default shield configuration. To ease use with applications,
+  the default shield configuration here should be consistent with those in
+  the :ref:`default_board_configuration`.
+
 * **dts_fixup.h**: This is a fixup file to bind board components definitions with
   application in a generic fashion to enable shield compatibility across boards
 
@@ -59,6 +65,20 @@ introduced overriding node element:
 
         arduino_i2c:i2c1{};
 
+Board specific shield configuration
+-----------------------------------
+
+If modifications are needed to fit a shield to a particular board, you can
+override a shield description for a specific board by adding board-overriding
+files to a shield, as follows:
+
+.. code-block:: none
+
+   boards/shields/<shield>
+   └── <boards>
+       ├── board.overlay
+       └── board.conf
+
 
 Shield activation
 *****************
@@ -77,3 +97,24 @@ Alternatively, it could be set by default in a project's CMakeLists.txt:
 .. code-block:: none
 
 	set(SHIELD x_nucleo_iks01a1)
+
+Shield variants
+***************
+
+Some shields may support several variants or revisions. In that case, it is
+possible to provide multiple version of the shields description:
+
+.. code-block:: none
+
+   boards/shields/<shield>
+   ├── <shield_v1>.overlay
+   ├── <shield_v1>.conf
+   ├── <shield_v2>.overlay
+   └── <shield_v2>.conf
+
+In this case, a shield-particular revision name can be used:
+
+  .. zephyr-app-commands::
+     :zephyr-app: your_app
+     :shield: shield_v2
+     :goals: build