doc/cli: add section about envvars, document VUNIT_VHDL_STANDARD (VUn…

…it#730)

docs/cli.rst

@@ -1,7 +1,7 @@
 .. _cli:
 
 Command Line Interface
-======================
+######################
 
 A :class:`VUnit <vunit.ui.VUnit>` object can be created from command
 line arguments by using the :meth:`from_argv
@@ -14,14 +14,15 @@ specified by the command line arguments and exit the script. The added
 source files are automatically scanned for test cases.
 
 Usage
------
+=====
 
 .. argparse::
    :ref: vunit.vunit_cli._parser_for_documentation
    :prog: run.py
 
 Example Session
----------------
+===============
+
 The :vunit_example:`VHDL User Guide Example <vhdl/user_guide/>` can be run to produce the following output:
 
 .. code-block:: console
@@ -89,7 +90,8 @@ The :vunit_example:`VHDL User Guide Example <vhdl/user_guide/>` can be run to pr
    All passed!
 
 Opening a Test Case in Simulator GUI
-------------------------------------
+====================================
+
 Sometimes the textual error messages and logs are not enough to
 pinpoint the error and a test case needs to be opened in the GUI for
 visual debugging using single stepping, breakpoints and wave form
@@ -130,7 +132,8 @@ possible to perform ``run.py`` with the ``--compile`` flag in a
 separate terminal.
 
 Test Output Paths
------------------
+=================
+
 VUnit creates a separate output directory for each test to provide
 isolation. The test output paths are located under
 ``OUTPUT_PATH/test_output/``. The test names have been washed of any
@@ -150,6 +153,11 @@ and then a test name.
    When using the ``run_all_in_same_sim`` pragma all tests within the
    test bench share the same output folder named after the test bench.
 
+.. _environment_variables:
+
+Environment Variables
+=====================
+
 .. _simulator_selection:
 
 Simulator Selection
@@ -170,8 +178,8 @@ path can be explicitly configured by setting a
 
    VUNIT_GHDL_PATH=/opt/ghdl/bin
 
-Simulator Specific Environment Variables
-----------------------------------------
+Simulator Specific
+------------------
 
 - ``VUNIT_MODELSIM_INI`` By default VUnit copies the *modelsim.ini*
   file from the tool install folder as a starting point. Setting this
@@ -180,8 +188,8 @@ Simulator Specific Environment Variables
 
 .. _test_output_envs:
 
-Test Output Path Length Environment Variables
----------------------------------------------
+Test Output Path Length
+-----------------------
 - ``VUNIT_SHORT_TEST_OUTPUT_PATHS`` Unfortunately file system paths
   are still practically limited to 260 characters on Windows. VUnit
   tries to limit the length of the test output paths on Windows to
@@ -195,10 +203,23 @@ Test Output Path Length Environment Variables
   output path margin on Windows. By default the test output path is
   shortened to allow a 100 character margin.
 
+Language revision selection
+---------------------------
+
+The VHDL revision can be specified through the :ref:`python_interface`
+(see :class:`vunit.ui.VUnit`).
+Alternatively, environment variable ``VUNIT_VHDL_STANDARD`` can be set to
+``93``|``1993``, ``02``|``2002``, ``08``|``2008`` (default) or ``19``|``2019``.
+
+.. 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:
 
 JSON Export
------------
+===========
+
 VUnit supports exporting project information through the ``--export-json`` command
 line argument. A JSON file is written containing the list of all files
 added to the project as well as a list of all tests. Each test has a

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+", encoding="utf-8")
-    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)):