VUnit · eine · Oct 22, 2019 · Oct 20, 2019 · Oct 21, 2019 · Oct 21, 2019
diff --git a/docs/cli.rst b/docs/cli.rst
@@ -2,13 +2,13 @@
 
 Command Line Interface
 ======================
-A :class:`VUnit <vunit.ui.VUnit>` object can be created from command
+A :class:`VUnit <vunit.ui.vunit.VUnit>` object can be created from command
 line arguments by using the :meth:`from_argv
-<vunit.ui.VUnit.from_argv>` method effectively creating a custom
+<vunit.ui.vunit.VUnit.from_argv>` method effectively creating a custom
 command line tool for running tests in the user project.  Source files
 and libraries are added to the project by using methods on the VUnit
 object. The configuration is followed by a call to the :meth:`main
-<vunit.ui.VUnit.main>` method which will execute the function
+<vunit.ui.vunit.VUnit.main>` method which will execute the function
 specified by the command line arguments and exit the script. The added
 source files are automatically scanned for test cases.
 

diff --git a/docs/conf.py b/docs/conf.py
@@ -174,6 +174,8 @@
     "ablog",
 ]
 
+autodoc_default_flags = ["members"]
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates", ablog.get_html_templates_path()]
 

diff --git a/docs/documentation.rst b/docs/documentation.rst
@@ -5,7 +5,7 @@ Documentation
 
    user_guide
    cli
-   python_interface
+   py/ui
    vhdl_libraries
    examples
 

diff --git a/docs/installing.rst b/docs/installing.rst
@@ -27,7 +27,7 @@ Start by cloning our `GIT repository on GitHub <https://github.com/vunit/vunit/>
 
 The ``--recursive`` option initializes `OSVVM <https://github.com/JimLewis/OSVVM>`__ which is included as a submodule in the VUnit repository.
 
-To be able to import :class:`VUnit <vunit.ui.VUnit>` in your ``run.py`` script
+To be able to import :class:`VUnit <vunit.ui.vunit.VUnit>` in your ``run.py`` script
 you need to make it visible to Python or else the following error
 occurs.
 

diff --git a/docs/py/opts.rst b/docs/py/opts.rst
@@ -0,0 +1,189 @@
+.. _compile_options:
+
+Compilation Options
+-------------------
+
+Compilation options allow customization of compilation behavior. Since simulators have
+differing options available, generic options may be specified through this interface.
+The following compilation options are known.
+
+``ghdl.flags``
+   Extra arguments passed to ``ghdl -a`` command during compilation.
+   Must be a list of strings.
+
+``incisive.irun_vhdl_flags``
+   Extra arguments passed to the Incisive ``irun`` command when compiling VHDL files.
+   Must be a list of strings.
+
+``incisive.irun_verilog_flags``
+   Extra arguments passed to the Incisive ``irun`` command when compiling Verilog files.
+   Must be a list of strings.
+
+``modelsim.vcom_flags``
+   Extra arguments passed to ModelSim ``vcom`` command.
+   Must be a list of strings.
+
+``modelsim.vlog_flags``
+   Extra arguments passed to ModelSim ``vlog`` command.
+   Must be a list of strings.
+
+``rivierapro.vcom_flags``
+   Extra arguments passed to Riviera PRO ``vcom`` command.
+   Must be a list of strings.
+
+``rivierapro.vlog_flags``
+   Extra arguments passed to Riviera PRO ``vlog`` command.
+   Must be a list of strings.
+
+``activehdl.vcom_flags``
+   Extra arguments passed to Active HDL ``vcom`` command.
+   Must be a list of strings.
+
+``activehdl.vlog_flags``
+   Extra arguments passed to Active HDL ``vcom`` command.
+   Must be a list of strings.
+
+.. note::
+   Only affects source files added *before* the option is set.
+
+.. _sim_options:
+
+Simulation Options
+------------------
+
+Simulation options allow customization of simulation behavior. Since simulators have
+differing options available, generic options may be specified through this interface.
+The following simulation options are known.
+
+``vhdl_assert_stop_level``
+  Will stop a VHDL simulation for asserts on the provided severity level or higher.
+  Valid values are ``"warning"``, ``"error"``, and ``"failure"``. This option takes
+  precedence over the fail_on_warning attribute.
+
+``disable_ieee_warnings``
+  Disable ieee warnings. Must be a boolean value. Default is False.
+
+.. _coverage:
+
+``enable_coverage``
+  Enables code coverage collection during simulator for the run affected by the sim_option.
+  Must be a boolean value. Default is False.
+
+  When coverage is enabled VUnit only takes the minimal steps required
+  to make the simulator creates an unique coverage file for the
+  simulation run. The VUnit users must still set :ref:`sim
+  <sim_options>` and :ref:`compile <compile_options>` options to
+  configure the simulator specific coverage options they want. The
+  reason for this to allow the VUnit users maximum control of their
+  coverage settings.
+
+  An example of a ``run.py`` file using coverage can be found
+  :vunit_example:`here <vhdl/coverage>`.
+
+  .. note: Supported by RivieraPRO and Modelsim/Questa simulators.
+
+
+``pli``
+  A list of PLI file names.
+
+``ghdl.flags``
+   Extra arguments passed to ``ghdl --elab-run`` command *before* executable specific flags.
+   Must be a list of strings.
+
+``incisive.irun_sim_flags``
+   Extra arguments passed to the Incisive ``irun`` command when loading the design.
+   Must be a list of strings.
+
+``modelsim.vsim_flags``
+   Extra arguments passed to ``vsim`` when loading the design.
+   Must be a list of strings.
+
+``modelsim.vsim_flags.gui``
+   Extra arguments passed to ``vsim`` when loading the design in GUI
+   mode where it takes precedence over ``modelsim.vsim_flags``.
+   Must be a list of strings.
+
+``modelsim.init_files.after_load``
+   A list of user defined DO/TCL-files that is sourced after the design has been loaded.
+   They will be executed during ``vunit_load``, after the top level has been loaded
+   using the ``vsim`` command.
+   During script evaluation the ``vunit_tb_path`` variable is defined
+   as the path of the folder containing the test bench.
+   Must be a list of strings.
+
+``modelsim.init_files.before_run``
+   A list of user defined DO/TCL-files that is sourced before the simulation is run.
+   They will be executed at the start of ``vunit_run`` (and therefore also re-executed
+   by ``vunit_restart``).
+   Must be a list of strings.
+
+``modelsim.init_file.gui``
+   A user defined TCL-file that is sourced after the design has been loaded in the GUI.
+   For example this can be used to configure the waveform viewer.
+   During script evaluation the ``vunit_tb_path`` variable is defined
+   as the path of the folder containing the test bench.
+   Must be a string.
+
+``rivierapro.vsim_flags``
+   Extra arguments passed to ``vsim`` when loading the design.
+   Must be a list of strings.
+
+``rivierapro.vsim_flags.gui``
+   Extra arguments passed to ``vsim`` when loading the design in GUI
+   mode where it takes precedence over ``rivierapro.vsim_flags``.
+   Must be a list of strings.
+
+``rivierapro.init_files.after_load``
+   A list of user defined DO/TCL-files that is sourced after the design has been loaded.
+   They will be executed during ``vunit_load``, after the top level has been loaded
+   using the ``vsim`` command.
+   During script evaluation the ``vunit_tb_path`` variable is defined
+   as the path of the folder containing the test bench.
+   Must be a list of strings.
+
+``rivierapro.init_files.before_run``
+   A list of user defined DO/TCL-files that is sourced before the simulation is run.
+   They will be executed at the start of ``vunit_run`` (and therefore also re-executed
+   by ``vunit_restart``).
+   Must be a list of strings.
+
+``rivierapro.init_file.gui``
+   A user defined TCL-file that is sourced after the design has been loaded in the GUI.
+   For example this can be used to configure the waveform viewer.
+   During script evaluation the ``vunit_tb_path`` variable is defined
+   as the path of the folder containing the test bench.
+   Must be a string.
+
+``activehdl.vsim_flags``
+   Extra arguments passed to ``vsim`` when loading the design.
+   Must be a list of strings.
+
+``activehdl.vsim_flags.gui``
+   Extra arguments passed to ``vsim`` when loading the design in GUI
+   mode where it takes precedence over ``activehdl.vsim_flags``.
+   Must be a list of strings.
+
+``activehdl.init_file.gui``
+   A user defined TCL-file that is sourced after the design has been loaded in the GUI.
+   For example this can be used to configure the waveform viewer.
+   Must be a string.
+
+``ghdl.elab_flags``
+   Extra elaboration flags passed to ``ghdl --elab-run``.
+   Must be a list of strings.
+
+``ghdl.sim_flags``
+   Extra simulation flags passed to ``ghdl --elab-run``.
+   Must be a list of strings.
+
+``ghdl.elab_e``
+   With ``--elaborate``, execute ``ghdl -e`` instead of ``ghdl --elab-run --no-run``.
+   Must be a boolean.
+
+``ghdl.gtkwave_script.gui``
+   A user defined TCL-file that is sourced after the design has been loaded in the GUI.
+   For example this can be used to configure the waveform viewer. Must be a string.
+   There are currently limitations in the HEAD revision of GTKWave that prevent the
+   user from sourcing a list of scripts directly. The following is the current work
+   around to sourcing multiple user TCL-files:
+   ``source <path/to/script.tcl>``
diff --git a/docs/python_interface.rst → docs/py/ui.rst b/docs/python_interface.rst → docs/py/ui.rst
@@ -3,11 +3,41 @@
 Python Interface
 ================
 The Python interface of VUnit is exposed through the :class:`VUnit
-<vunit.ui.VUnit>` class that can be imported directly from the
-:mod:`vunit <vunit.ui>` module.
-
-.. automodule:: vunit.ui
-
+class <vunit.ui.vunit.VUnit>` that can be imported directly. See the
+:ref:`User Guide <user_guide>` for a quick introduction. The
+following list provides detailed references of the Python API and
+about how to set compilation and simulation options.
+
+.. toctree::
+
+   vunit
+   opts
+
+.. _configurations:
+
+Configurations
+--------------
+In VUnit Python API the name ``configuration`` is used to denote the
+user controllable configuration of one test run such as
+generic/parameter settings, simulation options as well as the
+pre_config and post_check :ref:`callback functions <pre_and_post_hooks>`.
+User :ref:`attributes <attributes>` can also be added as a part of a
+configuration.
+
+Configurations can either be unique for each test case or must be
+common for the entire test bench depending on the situation.  For test
+benches without test such as `tb_example` in the User Guide the
+configuration is common for the entire test bench. For test benches
+containing tests such as `tb_example_many` the configuration is done
+for each test case. If the ``run_all_in_same_sim`` attribute has been used
+configuration is performed at the test bench level even if there are
+individual test within since they must run in the same simulation.
+
+In a VUnit all test benches and test cases are created with an unnamed default
+configuration which is modified by different methods such as ``set_generic`` etc.
+In addition to the unnamed default configuration multiple named configurations
+can be derived from it by using the ``add_config`` method. The default
+configuration is only run if there are no named configurations.
 
 .. _attributes:
 

diff --git a/docs/py/vunit.rst b/docs/py/vunit.rst
@@ -0,0 +1,46 @@
+vunit.ui.vunit
+==============
+
+.. autoclass:: vunit.ui.vunit.VUnit()
+   :exclude-members: add_preprocessor,
+      add_builtins
+
+Library
+-------
+
+.. autoclass:: vunit.ui.library.Library()
+   :exclude-members: package
+
+SourceFileList
+--------------
+
+.. autoclass:: vunit.ui.source.SourceFileList()
+
+SourceFile
+----------
+
+.. autoclass:: vunit.ui.source.SourceFile()
+
+TestBench
+---------
+
+.. autoclass:: vunit.ui.testbench.TestBench()
+
+Test
+----
+
+.. autoclass:: vunit.ui.test.Test()
+
+Results
+-------
+
+.. autoclass:: vunit.ui.results.Results()
+
+.. |compile_option| replace::
+   The name of the compile option (See :ref:`Compilation options <compile_options>`)
+
+.. |simulation_options| replace::
+   The name of the simulation option (See :ref:`Simulation options <sim_options>`)
+
+.. |configurations| replace::
+    :ref:`configurations <configurations>`
diff --git a/docs/run/user_guide.rst b/docs/run/user_guide.rst
@@ -10,7 +10,7 @@ The VHDL run library is a number of VHDL packages providing functionality for ru
 This functionality is also known as the VHDL test runner (VR). It's possible to run a VUnit testbench standalone,
 just using VR, but the highly recommended approach and the main focus of this user guide is to use VR together
 with the Python-based test runner (PR) documented in this :doc:`user guide <../user_guide>` and
-:doc:`API documentation <../python_interface>`.
+:doc:`API documentation <../py/ui>`.
 
 Minimal VUnit Testbench
 -----------------------
@@ -258,7 +258,7 @@ And the lower-level entity like this
 
 The default PR behaviour is to scan all VHDL files with an entity containing a ``runner_cfg`` generic for
 test cases to run. Now that that the lower-level entity uses another generic name you have to use the
-:doc:`scan_tests_from_file <../python_interface>` method in your run script.
+:doc:`scan_tests_from_file <../py/vunit>` method in your run script.
 
 Controlling What Test Cases to Run
 ----------------------------------

diff --git a/setup.py b/setup.py
@@ -42,13 +42,14 @@ def find_all_files(directory, endings=None):
     packages=[
         "vunit",
         "vunit.com",
-        "vunit.test",
         "vunit.parsing",
         "vunit.parsing.verilog",
-        "vunit.vivado",
+        "vunit.test",
         "vunit.test.lint",
         "vunit.test.unit",
         "vunit.test.acceptance",
+        "vunit.ui",
+        "vunit.vivado",
     ],
     package_data={"vunit": DATA_FILES},
     zip_safe=False,

diff --git a/vunit/__init__.py b/vunit/__init__.py
@@ -10,7 +10,7 @@
 
 from os.path import dirname, join, abspath
 import vunit.version_check
-from vunit.ui import VUnit
+from vunit.ui.vunit import VUnit
 from vunit.vunit_cli import VUnitCLI
 from vunit.about import version, doc
 from vunit.json4vhdl import read_json, encode_json