Updated documentation.

README.md

@@ -7,16 +7,16 @@ VUnit is an open source unit testing framework for VHDL released under the terms
 The VUnit project mission is to apply best SW testing practises to the world of VHDL by providing the tools missing to adapt to such practises. The major missing piece is the unit testing framework, hence the name V(HDL)Unit. However, VUnit also provides supporting functionality not normally considered as a part of an unit testing framework. 
 
 # Main Features
-* Builds on the commonly used [xUnit](http://en.wikipedia.org/wiki/XUnit) architecture
-* Python test runner that enables powerful test administration, can handle VHDL fatal run-time errors (e.g. division by zero), and ensures test case independence
-* Scanners for identifying files, tests, file dependencies, and file changes enable for automatic (re)compilation and execution of test suites
-* Scripting as well as command line support
-* Support for running same tests with different generics
-* VHDL test runner which enables test execution for not fully supported simulators
-* Assertion checker library that extends VHDL built-in support (assert)
-* Logging framework supporting display and file output, different log levels, filtering on level/design hierarchy, output formatting and multiple loggers. Spreadsheet tool integration.
-* Location preprocessor that traces log and check calls back to file and line number
-* JUnit report files for better [Jenkins](http://jenkins-ci.org/) integration
+* Builds on the commonly used [xUnit](http://en.wikipedia.org/wiki/XUnit) architecture.
+* Python test runner that enables powerful test administration, can handle VHDL fatal run-time errors (e.g. division by zero), and ensures test case independence.
+* Scanners for identifying files, tests, file dependencies, and file changes enable for automatic (re)compilation and execution of test suites.
+* Scripting as well as command line support.
+* Support for running same test suite with different generics.
+* VHDL test runner which enables test execution for not fully supported simulators.
+* Assertion checker library that extends VHDL built-in support (assert).
+* Logging framework supporting display and file output, different log levels, filtering on level and design hierarchy, output formatting and multiple loggers. Spreadsheet tool integration.
+* Location preprocessor that traces log and check calls back to file and line number.
+* JUnit report files for better [Jenkins](http://jenkins-ci.org/) integration.
 
 # Requirements
 VUnit depends on a number of components as listed below. Full VUnit functionality requires Python and a simulator supported by the VUnit Python test runner. However, VUnit can run with limited functionality entirely within VHDL which means that unsupported simulators can be used as well. Prototype work has been done to fully support other simulators but this work is yet to be completed and released.
@@ -37,9 +37,14 @@ VUnit depends on a number of components as listed below. Full VUnit functionalit
 * Mentor Graphics ModelSim (tested with 10.1 - 10.3)
 
 # Getting Started
+There are a number of ways to get started.
+
+*  Have a look at the examples under examples/. The examples in examples/logging and examples/check are tutorials that should be single-stepped in your simulator.
+*  The user guide will give an introduction on how VUnit is used with Python scripting and from the command line
+*  There are also various presentations of VUnit on [YouTube](https://www.youtube.com/channel/UCCPVCaeWkz6C95aRUTbIwdg)
 
 # Main Contributors
-Lars Asplund
+Lars Asplund  
 Olof Kraigher
 
 # License 

user_guide.md

@@ -0,0 +1,150 @@
+# VUnit User Guide
+# Python Interface
+
+The public interface of VUnit is exposed through the `VUnit` class
+that can be imported directly from the vunit module.
+
+```python
+# file: run.py
+import vunit
+
+# Create VUnit instance by parsing command line arguments
+vu = VUnit.from_argv()
+
+# Create library 'lib' 
+lib = vu.add_library("lib")
+
+# Add all files ending in .vhd in current working directory 
+lib.add_source_files("*.vhd")
+
+# Run vunit function
+vu.main()
+```
+
+A `VUnit` object can be created from command line arguments by using
+the `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 `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.
+
+```shell
+> python run.py -h
+usage: run.py [-h] [-l] [--compile] [--clean] [-o OUTPUT_PATH] [-x XUNIT_XML]
+              [-v] [--no-color] [--log-level {info,error,warning,debug}]
+              [tests [tests ...]]
+
+VUnit command line tool.
+
+positional arguments:
+  tests                 Tests to run
+
+optional arguments:
+  -h, --help            show this help message and exit
+  -l, --list            Only list all test cases
+  --compile             Only compile project
+  --clean               Remove output path first
+  -o OUTPUT_PATH, --output-path OUTPUT_PATH
+                        Output path for compilation and simulation artifacts
+  -x XUNIT_XML, --xunit-xml XUNIT_XML
+                        Xunit test report .xml file
+  -v, --verbose         Print test output immediately and not only when
+                        failure
+  --no-color            Do not color output
+  --log-level {info,error,warning,debug}
+```
+
+## VHDL Test Benches
+In its simplest form a VUnit VHDL test bench looks like this:
+```vhdl
+-- file tb_example.vhd
+library vunit_lib;
+context vunit_lib.vunit_context;
+
+entity tb_example is
+  generic (runner_cfg : runner_cfg_t);
+end entity;
+
+architecture tb of tb_example is
+begin
+  main : process
+  begin
+    test_runner_setup(runner, runner_cfg);
+    report "Hello world!";
+    test_runner_cleanup(runner); -- Simulation ends here
+  end process;
+end architecture;
+```
+
+From `tb_example.vhd` a single test case named `lib.tb_example` is
+created.  It is also possible to put multiple tests in a single test
+benchs that are each run in individual simulations. Putting multiple
+tests in the same test bench is a good way to share a common test
+environment.
+
+```vhdl
+-- file tb_example_many.vhd
+library vunit_lib;
+context vunit_lib.vunit_context;
+
+entity tb_example_many is
+  generic (runner_cfg : runner_cfg_t);
+end entity;
+
+architecture tb of tb_example_many is
+begin
+  main : process
+  begin
+    test_runner_setup(runner, runner_cfg);
+    
+    while test_suite loop
+      
+      if run("test_pass") then
+        report "This will pass";
+        
+      elsif run("test_fail") then
+        assert false report "It fails";
+        
+      end if;
+    end loop;
+    
+    test_runner_cleanup(runner);
+  end process;
+end architecture;
+```
+
+From `tb_example_many.vhd` two test cases named
+`lib.tb_example_many.test_pass` and `tb_example_many.test_fail` are
+created.
+
+We can run these test using `run.py` command line interface:
+```shell
+> python run.py -v lib.tb_example*
+Running test: lib.tb_example
+Running test: lib.tb_example_many.test_pass
+Running test: lib.tb_example_many.test_fail
+Running 3 tests
+running lib.tb_example
+Hello World!
+pass (P=1 F=0 T=3) lib.tb_example
+
+running lib.tb_example.test_pass
+This will pass
+pass (P=2 F=0 T=3) lib.tb_example_many.test_pass
+
+running lib.tb_example.test_fail
+Error: It fails
+fail (P=2 F=1 T=3) lib.tb_example_many.test_fail
+
+pass lib.tb_example after 0.1 seconds
+pass lib.tb_example_many.test_pass after 0.1 seconds
+fail lib.tb_example_many.test_fail after 0.1 seconds
+
+Total time 0.3 seconds
+2 of 3 passed
+Some failed!
+```
+
+The above example code can be found in `examples/user_guide/`.