doc: restructure and distribute feature flags/@pytest.mark.lg_feature docs

The feature flags are not a pytest plugin feature. Instead they should
be described in the configuration chapter in the environment config
section. So move them there.

The pytest plugin docs should, however, document
@pytest.mark.lg_feature, so name the section accordingly and simplify
the section, so the relevant parts are described there in a pointed
fashion.

Signed-off-by: Bastian Krause <bst@pengutronix.de>

Author: Bastian-Krause

doc/configuration.rst

@@ -3756,6 +3756,45 @@ See the :ref:`labgrid-device-config` man page for documentation on the
 top-level ``options``, ``images``, ``tools``, and ``imports`` keys in the
 environment configuration.
 
+.. _environment-configuration-feature-flags:
+
+Feature Flags
+~~~~~~~~~~~~~
+Similar targets or multi target environments may differ from each other in
+certain small aspects, e.g. one device has a camera or screen connected, but
+another one has not.
+In labgrid's environment configs, such variations are described as feature flags.
+
+Here's an example environment configuration for a target-scoped feature
+``camera``:
+
+.. code-block:: yaml
+  :name: feature-flag-env.yaml
+
+  targets:
+    main:
+      features:
+        - camera
+      resources: {}
+      drivers: {}
+
+Features can not only be set per target, but also globally:
+
+.. code-block:: yaml
+  :name: feature-flag-global-env.yaml
+
+  features:
+    - camera
+  targets:
+    main:
+      features:
+        - console
+      resources: {}
+      drivers: {}
+
+See :ref:`usage_pytestplugin_mark_lg_feature` for how to make use of feature
+flags in tests.
+
 Multiple Drivers of the Same Type
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 If you want to use multiple drivers of the same type, the resources and drivers

doc/usage.rst

@@ -699,117 +699,37 @@ For this example, you should get a report similar to this:
 
   ========================== 3 passed in 29.77 seconds ===========================
 
-Feature Flags
-~~~~~~~~~~~~~
-labgrid includes support for feature flags on a global and target scope.
-Adding a ``@pytest.mark.lg_feature`` decorator to a test ensures it is only
-executed if the desired feature is available:
+.. _usage_pytestplugin_mark_lg_feature:
+
+@pytest.mark.lg_feature()
+~~~~~~~~~~~~~~~~~~~~~~~~~
+labgrid supports :ref:`environment-configuration-feature-flags` in the
+:ref:`environment-configuration`.
+Adding a ``@pytest.mark.lg_feature()`` decorator to a test ensures it is only
+executed if the desired feature is set, either under the target or global
+``features:`` keys.
 
 .. code-block:: python
-   :name: test_feature_flags.py
 
    import pytest
 
    @pytest.mark.lg_feature("camera")
    def test_camera(target):
       pass
 
-Here's an example environment configuration:
-
-.. code-block:: yaml
-  :name: feature-flag-env.yaml
-
-  targets:
-    main:
-      features:
-        - camera
-      resources: {}
-      drivers: {}
+In case the feature is unavailable, pytest will record the missing feature
+as the skip reason.
 
-.. testcode:: pytest-example
-  :hide:
-
-  import pytest
-
-  plugins = ['labgrid.pytestplugin']
-  pytest.main(['--lg-env', 'feature-flag-env.yaml', 'test_feature_flags.py'], plugins)
-
-.. testoutput:: pytest-example
-  :hide:
-
-  ... 1 passed...
-
-This would run the above test, however the following configuration would skip the
-test because of the missing feature:
-
-.. code-block:: yaml
-  :name: feature-flag-skip-env.yaml
-
-  targets:
-    main:
-      features:
-        - console
-      resources: {}
-      drivers: {}
-
-.. testcode:: pytest-example
-  :hide:
-
-  import pytest
-
-  plugins = ['labgrid.pytestplugin']
-  pytest.main(['--lg-env', 'feature-flag-skip-env.yaml', 'test_feature_flags.py'], plugins)
-
-.. testoutput:: pytest-example
-  :hide:
-
-  ... 1 skipped...
-
-pytest will record the missing feature as the skip reason.
-
-For tests with multiple required features, pass them as a list to pytest:
+Tests requiring multiple features are also possible:
 
 .. code-block:: python
-   :name: test_feature_flags_global.py
 
    import pytest
 
    @pytest.mark.lg_feature(["camera", "console"])
    def test_camera(target):
       pass
 
-Features do not have to be set per target, they can also be set via the global
-features key:
-
-.. code-block:: yaml
-  :name: feature-flag-global-env.yaml
-
-  features:
-    - camera
-  targets:
-    main:
-      features:
-        - console
-      resources: {}
-      drivers: {}
-
-.. testcode:: pytest-example
-  :hide:
-
-  import pytest
-
-  plugins = ['labgrid.pytestplugin']
-  pytest.main(['--lg-env', 'feature-flag-global-env.yaml', 'test_feature_flags_global.py'],
-              plugins)
-
-.. testoutput:: pytest-example
-  :hide:
-
-  ... 1 passed...
-
-This YAML configuration would combine both the global and the target features.
-
-
 Test Reports
 ~~~~~~~~~~~~