docs: add 'examples_intro'

docs/cli.rst

@@ -211,9 +211,9 @@ The VHDL revision can be specified through the :ref:`python_interface`
 Alternatively, environment variable ``VUNIT_VHDL_STANDARD`` can be set to
 ``93``|``1993``, ``02``|``2002``, ``08``|``2008`` (default) or ``19``|``2019``.
 
-.. warning:: the specification of an unsupported revision produces an ERROR.
-             Moreover, take into account that `context`` statement is not supported
-             previous 2008, so it must be replace with multiple ``use`` statements.
+.. IMPORTANT::
+  Note that VHDL revision 2019 is unsupported by most vendors, and support of VHDL 2008 features is uneven.
+  Check the documentation of the simulator before using features requiring revisions equal or newer than 2008.
 
 .. _json_export:
 

docs/examples_intro.rst

@@ -0,0 +1,7 @@
+.. HINT::
+  Most of the examples expect the simulator to support several VHDL 2008 features.
+  This is made explicit by using ``context`` instead of multiple ``use`` statements.
+  However, some vendors do support enough VHDL 2008 features in order to run some of the examples, but they cannot
+  handle contexts.
+  In those cases, replacing ``context vunit_lib.vunit_context`` with the content of :vunit_file:`vunit/vhdl/vunit_context.vhd`
+  and :vunit_file:`vunit/vhdl/data_types/src/data_types_context.vhd` might work.

tools/docs_utils.py

@@ -25,7 +25,16 @@ def examples():
     """
     eg_path = ROOT.parent / "examples"
     egs_fptr = (ROOT / "examples.rst").open("w+")
-    egs_fptr.write("\n".join([".. _examples:\n", "Examples", "========", "\n"]))
+    egs_fptr.write(
+        "\n".join(
+            [
+                ".. _examples:\n",
+                "Examples",
+                "========\n",
+                ".. include:: examples_intro.rst\n",
+            ]
+        )
+    )
     for language, subdir in {"VHDL": "vhdl", "SystemVerilog": "verilog"}.items():
         egs_fptr.write("\n".join([language, "~~~~~~~~~~~~~~~~~~~~~~~", "\n"]))
         for item in listdir(str(eg_path / subdir)):