diff --git a/.gitignore b/.gitignore
index f91a4ebcd..00acfb837 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,2 +1,4 @@
 **/vunit_out
-*.pyc
\ No newline at end of file
+*.pyc
+docs/examples.rst
+docs/release_notes.rst
\ No newline at end of file
diff --git a/docs/documentation.rst b/docs/documentation.rst
index 96f356393..7fa0e7483 100644
--- a/docs/documentation.rst
+++ b/docs/documentation.rst
@@ -7,5 +7,6 @@ Documentation
    cli
    python_interface
    vhdl_libraries
+   examples
 
 * :ref:`genindex`
diff --git a/docs/user_guide.rst b/docs/user_guide.rst
index ed749fbb1..3a2df0c3e 100644
--- a/docs/user_guide.rst
+++ b/docs/user_guide.rst
@@ -166,78 +166,3 @@ the test bench.
   Optional path to the directory containing the test bench.
   This is useful to read input data with a known location relative to
   the test bench location.
-
-.. _examples:
-
-Examples
---------
-There are many examples demonstrating more specific usage of VUnit listed below:
-
-:vunit_example:`VHDL User Guide Example <vhdl/user_guide>`
-  The most minimal VUnit VHDL project covering the basics of this user
-  guide.
-
-:vunit_example:`SystemVerilog User Guide Example <verilog/user_guide>`
-  The most minimal VUnit SystemVerilog project covering the basics of
-  this user guide.
-
-:vunit_example:`VHDL UART Example <vhdl/uart>`
-  A more realistic test bench of an UART to show VUnit VHDL usage on a
-  typical module.
-
-:vunit_example:`SystemVerilog UART Example <verilog/uart>`
-  A more realistic test bench of an UART to show VUnit SystemVerilog
-  usage on a typical module.
-
-:vunit_example:`Run Example <vhdl/run>`
-  Demonstrates the VUnit run library.
-
-:vunit_example:`Check Example <vhdl/check>`
-  Demonstrates the VUnit check library.
-
-:vunit_example:`Logging Example <vhdl/logging>`
-  Demonstrates VUnit's support for logging.
-
-:vunit_example:`Array Example <vhdl/array>`
-  Demonstrates the ``array_t`` data type of ``array_pkg.vhd`` which
-  can be used to handle dynamically sized 1D, 2D and 3D data as well
-  as storing and loading it from csv and raw files.
-
-:vunit_example:`AXI DMA <vhdl/axi_dma>`
-  Demonstrates the AXI read and write slave verification components as
-  well as the AXI-lite master verification component. An AXI DMA is
-  verified which uses an AXI master port to read and write data from
-  external memory.  The AXI DMA also has a control register interface
-  via AXI-lite.
-
-:vunit_example:`Array and AXI4 Stream Verification Components Example <vhdl/array_axis_vcs>`
-  Demonstrates ``array_t``, ``axi_stream_master_t`` and ``axi_stream_slave_t``
-  data types of ``array_pkg.vhd``, ``stream_master_pkg`` and ``stream_slave_pkg``,
-  respectively. Also, ``push_axi_stream`` of ``axi_stream_pkg`` is used. A CSV file
-  is read, the content is sent in a row-major order to an AXI Stream buffer (FIFO)
-  and it is received back to be saved in a different file. Further information can
-  be found in the :ref:`verification component library user guide <vc_library>`,
-  in subsection :ref:`Stream <stream_vci>` and in
-  :vunit_file:`vhdl/verification_components/test/tb_axi_stream.vhd <vunit/vhdl/verification_components/test/tb_axi_stream.vhd>`.
-
-:vunit_example:`Generating tests <vhdl/generate_tests>`
-  Demonstrates generating multiple test runs of the same test bench
-  with different generic values. Also demonstrates use of ``output_path`` generic
-  to create test bench output files in location specified by VUnit python runner.
-
-:vunit_example:`Vivado IP example <vhdl/vivado>`
-  Demonstrates compiling and performing behavioral simulation of
-  Vivado IPs with VUnit.
-
-:vunit_example:`Communication library example <vhdl/com>`
-  Demonstrates the ``com`` message passing package which can be used
-  to communicate arbitrary objects between processes.  Further reading
-  can be found in the :ref:`com user guide <com_user_guide>`
-
-:vunit_example:`Composite generics <vhdl/composite_generics>`
-  See `Enable Your Simulator to Handle Complex Top-Level Generics <https://vunit.github.io/posts/2017_06_03_enable_your_simulator_to_handle_complex_top_level_generics/post.html>`_
-
-:vunit_example:`JSON-for-VHDL example <vhdl/json4vhdl>`
-  Demonstrates the ``JSON-for-VHDL`` library which can be used to parse JSON content.
-  The content can be read from a file, or passed as a stringified generic.
-  This is an alternative to composite generics, that supports any depth in the content structure.
diff --git a/examples/verilog/uart/run.py b/examples/verilog/uart/run.py
index c56301317..a92f92ee1 100644
--- a/examples/verilog/uart/run.py
+++ b/examples/verilog/uart/run.py
@@ -4,6 +4,14 @@
 #
 # Copyright (c) 2014-2019, Lars Asplund lars.anders.asplund@gmail.com
 
+"""
+SystemVerilog UART
+------------------
+
+A more realistic test bench of an UART to show VUnit SystemVerilog
+usage on a typical module.
+"""
+
 from os.path import join, dirname
 from vunit.verilog import VUnit
 
@@ -17,4 +25,5 @@
 tb_uart_lib = ui.add_library("tb_uart_lib")
 tb_uart_lib.add_source_files(join(src_path, "test", "*.sv"))
 
-ui.main()
+if __name__ == '__main__':
+    ui.main()
diff --git a/examples/verilog/user_guide/run.py b/examples/verilog/user_guide/run.py
index 9a0d87bf9..6e9f8564c 100644
--- a/examples/verilog/user_guide/run.py
+++ b/examples/verilog/user_guide/run.py
@@ -4,6 +4,14 @@
 #
 # Copyright (c) 2014-2019, Lars Asplund lars.anders.asplund@gmail.com
 
+"""
+SystemVerilog User Guide
+------------------------
+
+The most minimal VUnit SystemVerilog project covering the basics of
+the :ref:`User Guide <user_guide>`.
+"""
+
 from os.path import join, dirname
 from vunit.verilog import VUnit
 
@@ -12,4 +20,6 @@
 ui = VUnit.from_argv()
 lib = ui.add_library("lib")
 lib.add_source_files(join(root, "*.sv"))
-ui.main()
+
+if __name__ == '__main__':
+    ui.main()
diff --git a/examples/verilog/verilog_ams/run.py b/examples/verilog/verilog_ams/run.py
index 00ad25c45..800d4ed05 100644
--- a/examples/verilog/verilog_ams/run.py
+++ b/examples/verilog/verilog_ams/run.py
@@ -13,4 +13,6 @@
 lib = ui.add_library("lib")
 lib.add_source_files(join(root, "*.sv"))
 lib.add_source_files(join(root, "*.vams")).set_compile_option("modelsim.vlog_flags", ["-ams"])
-ui.main()
+
+if __name__ == '__main__':
+    ui.main()
diff --git a/examples/vhdl/array/run.py b/examples/vhdl/array/run.py
index db240eb95..380b43df8 100644
--- a/examples/vhdl/array/run.py
+++ b/examples/vhdl/array/run.py
@@ -4,6 +4,15 @@
 #
 # Copyright (c) 2014-2019, Lars Asplund lars.anders.asplund@gmail.com
 
+"""
+Array
+-----
+
+Demonstrates the ``array_t`` data type of ``array_pkg.vhd`` which
+can be used to handle dynamically sized 1D, 2D and 3D data as well
+as storing and loading it from csv and raw files.
+"""
+
 from os.path import join, dirname
 from vunit import VUnit
 
@@ -15,4 +24,6 @@
 lib = ui.add_library("lib")
 lib.add_source_files(join(root, "src", "*.vhd"))
 lib.add_source_files(join(root, "src", "test", "*.vhd"))
-ui.main()
+
+if __name__ == '__main__':
+    ui.main()
diff --git a/examples/vhdl/array_axis_vcs/run.py b/examples/vhdl/array_axis_vcs/run.py
index 4f0027c00..27af6730d 100644
--- a/examples/vhdl/array_axis_vcs/run.py
+++ b/examples/vhdl/array_axis_vcs/run.py
@@ -4,6 +4,20 @@
 #
 # Copyright (c) 2014-2019, Lars Asplund lars.anders.asplund@gmail.com
 
+"""
+Array and AXI4 Stream Verification Components
+---------------------------------------------
+
+Demonstrates ``array_t``, ``axi_stream_master_t`` and ``axi_stream_slave_t``
+data types of ``array_pkg.vhd``, ``stream_master_pkg`` and ``stream_slave_pkg``,
+respectively. Also, ``push_axi_stream`` of ``axi_stream_pkg`` is used. A CSV file
+is read, the content is sent in a row-major order to an AXI Stream buffer (FIFO)
+and it is received back to be saved in a different file. Further information can
+be found in the :ref:`verification component library user guide <vc_library>`,
+in subsection :ref:`Stream <stream_vci>` and in
+:vunit_file:`vhdl/verification_components/test/tb_axi_stream.vhd <vunit/vhdl/verification_components/test/tb_axi_stream.vhd>`.
+"""
+
 from os.path import join, dirname
 from vunit import VUnit
 
@@ -21,4 +35,5 @@
 
 # vu.set_sim_option('modelsim.init_files.after_load',['runall_addwave.do'])
 
-vu.main()
+if __name__ == '__main__':
+    vu.main()
diff --git a/examples/vhdl/axi_dma/run.py b/examples/vhdl/axi_dma/run.py
index d350d01b5..41dbfeccb 100644
--- a/examples/vhdl/axi_dma/run.py
+++ b/examples/vhdl/axi_dma/run.py
@@ -4,6 +4,17 @@
 #
 # Copyright (c) 2014-2019, Lars Asplund lars.anders.asplund@gmail.com
 
+"""
+AXI DMA
+-------
+
+Demonstrates the AXI read and write slave verification components as
+well as the AXI-lite master verification component. An AXI DMA is
+verified which uses an AXI master port to read and write data from
+external memory. The AXI DMA also has a control register interface
+via AXI-lite.
+"""
+
 from os.path import join, dirname
 from vunit import VUnit
 
@@ -17,4 +28,5 @@
 axi_dma_lib.add_source_files(join(src_path, "*.vhd"))
 axi_dma_lib.add_source_files(join(src_path, "test", "*.vhd"))
 
-ui.main()
+if __name__ == '__main__':
+    ui.main()
diff --git a/examples/vhdl/check/run.py b/examples/vhdl/check/run.py
index 786ca437d..4d7716c84 100644
--- a/examples/vhdl/check/run.py
+++ b/examples/vhdl/check/run.py
@@ -4,6 +4,13 @@
 #
 # Copyright (c) 2014-2019, Lars Asplund lars.anders.asplund@gmail.com
 
+"""
+Check
+-----
+
+Demonstrates the VUnit check library.
+"""
+
 from os.path import join, dirname
 from vunit import VUnit
 
@@ -20,4 +27,5 @@
 lib = ui.add_library("lib")
 lib.add_source_files(join(dirname(__file__), "tb_example.vhd"))
 
-ui.main()
+if __name__ == '__main__':
+    ui.main()
diff --git a/examples/vhdl/com/run.py b/examples/vhdl/com/run.py
index 4a23aea93..8712e0fb6 100644
--- a/examples/vhdl/com/run.py
+++ b/examples/vhdl/com/run.py
@@ -4,6 +4,15 @@
 #
 # Copyright (c) 2014-2019, Lars Asplund lars.anders.asplund@gmail.com
 
+"""
+Communication library
+---------------------
+
+Demonstrates the ``com`` message passing package which can be used
+to communicate arbitrary objects between processes.  Further reading
+can be found in the :ref:`com user guide <com_user_guide>`.
+"""
+
 from os.path import join, dirname
 from vunit import VUnit
 
@@ -18,4 +27,5 @@
 tb_lib = prj.add_library('tb_lib')
 tb_lib.add_source_files(join(dirname(__file__), 'test', '*.vhd'))
 
-prj.main()
+if __name__ == '__main__':
+    prj.main()
diff --git a/examples/vhdl/composite_generics/run.py b/examples/vhdl/composite_generics/run.py
index c746d2eed..5381339c1 100644
--- a/examples/vhdl/composite_generics/run.py
+++ b/examples/vhdl/composite_generics/run.py
@@ -4,6 +4,13 @@
 #
 # Copyright (c) 2014-2019, Lars Asplund lars.anders.asplund@gmail.com
 
+"""
+Composite generics
+------------------
+
+See `Enable Your Simulator to Handle Complex Top-Level Generics <https://vunit.github.io/posts/2017_06_03_enable_your_simulator_to_handle_complex_top_level_generics/post.html>`_.
+"""
+
 from os.path import join, dirname
 from vunit import VUnit
 
@@ -26,4 +33,5 @@ def encode(tb_cfg):
 tiny_tb_cfg = dict(image_width=4, image_height=3, dump_debug_data=True)
 test_1.add_config(name='tiny', generics=dict(encoded_tb_cfg=encode(tiny_tb_cfg)))
 
-prj.main()
+if __name__ == '__main__':
+    prj.main()
diff --git a/examples/vhdl/coverage/run.py b/examples/vhdl/coverage/run.py
index c4cb54f6a..6c42142e9 100644
--- a/examples/vhdl/coverage/run.py
+++ b/examples/vhdl/coverage/run.py
@@ -22,4 +22,5 @@
 def post_run(results):
     results.merge_coverage(file_name="coverage_data")
 
-ui.main(post_run=post_run)
+if __name__ == '__main__':
+    ui.main(post_run=post_run)
diff --git a/examples/vhdl/generate_tests/run.py b/examples/vhdl/generate_tests/run.py
index 1a8ad027c..5fc5f1c5f 100644
--- a/examples/vhdl/generate_tests/run.py
+++ b/examples/vhdl/generate_tests/run.py
@@ -4,6 +4,15 @@
 #
 # Copyright (c) 2014-2019, Lars Asplund lars.anders.asplund@gmail.com
 
+"""
+Generating tests
+----------------
+
+Demonstrates generating multiple test runs of the same test bench
+with different generic values. Also demonstrates use of ``output_path`` generic
+to create test bench output files in location specified by VUnit python runner.
+"""
+
 from os.path import join, dirname
 from itertools import product
 from vunit import VUnit
@@ -72,4 +81,5 @@ def generate_tests(obj, signs, data_widths):
         # Run all other tests with signed/unsigned and data width in range [1,5[
         generate_tests(test, [False, True], range(1, 5))
 
-ui.main()
+if __name__ == '__main__':
+    ui.main()
diff --git a/examples/vhdl/json4vhdl/run.py b/examples/vhdl/json4vhdl/run.py
index 84ffaa2dd..f7d755d50 100644
--- a/examples/vhdl/json4vhdl/run.py
+++ b/examples/vhdl/json4vhdl/run.py
@@ -4,6 +4,15 @@
 #
 # Copyright (c) 2014-2019, Lars Asplund lars.anders.asplund@gmail.com
 
+"""
+JSON-for-VHDL
+-------------
+
+Demonstrates the ``JSON-for-VHDL`` library which can be used to parse JSON content.
+The content can be read from a file, or passed as a stringified generic.
+This is an alternative to composite generics, that supports any depth in the content structure.
+"""
+
 from os.path import join, dirname
 from vunit import VUnit, read_json, encode_json
 
@@ -20,4 +29,5 @@
 tb_cfg["dump_debug_data"]=False
 vu.set_generic("tb_cfg", encode_json(tb_cfg))
 
-vu.main()
+if __name__ == '__main__':
+    vu.main()
diff --git a/examples/vhdl/logging/run.py b/examples/vhdl/logging/run.py
index 8e78b7807..d368e2125 100644
--- a/examples/vhdl/logging/run.py
+++ b/examples/vhdl/logging/run.py
@@ -4,6 +4,13 @@
 #
 # Copyright (c) 2014-2019, Lars Asplund lars.anders.asplund@gmail.com
 
+"""
+Logging
+-------
+
+Demonstrates VUnit's support for logging.
+"""
+
 from os.path import join, dirname
 from vunit import VUnit
 
@@ -11,4 +18,5 @@
 lib = ui.add_library("lib")
 lib.add_source_files(join(dirname(__file__), "*.vhd"))
 
-ui.main()
+if __name__ == '__main__':
+    ui.main()
diff --git a/examples/vhdl/run/run.py b/examples/vhdl/run/run.py
index fe94b66d8..00790f2d1 100644
--- a/examples/vhdl/run/run.py
+++ b/examples/vhdl/run/run.py
@@ -4,6 +4,13 @@
 #
 # Copyright (c) 2014-2019, Lars Asplund lars.anders.asplund@gmail.com
 
+"""
+Run
+---
+
+Demonstrates the VUnit run library.
+"""
+
 from os.path import join, dirname
 from vunit import VUnit
 
@@ -14,4 +21,6 @@
 lib.add_source_files(join(root, "*.vhd"))
 tb_with_lower_level_control = lib.entity("tb_with_lower_level_control")
 tb_with_lower_level_control.scan_tests_from_file(join(root, "test_control.vhd"))
-ui.main()
+
+if __name__ == '__main__':
+    ui.main()
diff --git a/examples/vhdl/third_party_integration/run.py b/examples/vhdl/third_party_integration/run.py
index a2bd47d0d..99c420cd4 100644
--- a/examples/vhdl/third_party_integration/run.py
+++ b/examples/vhdl/third_party_integration/run.py
@@ -12,4 +12,6 @@
 
 lib = ui.add_library("lib")
 lib.add_source_files(join(root, 'test', '*.vhd'))
-ui.main()
+
+if __name__ == '__main__':
+    ui.main()
diff --git a/examples/vhdl/uart/run.py b/examples/vhdl/uart/run.py
index 930f561e7..4c46f8c92 100644
--- a/examples/vhdl/uart/run.py
+++ b/examples/vhdl/uart/run.py
@@ -4,6 +4,14 @@
 #
 # Copyright (c) 2014-2019, Lars Asplund lars.anders.asplund@gmail.com
 
+"""
+VHDL UART
+---------
+
+A more realistic test bench of an UART to show VUnit VHDL usage on a
+typical module.
+"""
+
 from os.path import join, dirname
 from vunit import VUnit
 
@@ -19,4 +27,5 @@
 tb_uart_lib = ui.add_library("tb_uart_lib")
 tb_uart_lib.add_source_files(join(src_path, "test", "*.vhd"))
 
-ui.main()
+if __name__ == '__main__':
+    ui.main()
diff --git a/examples/vhdl/user_guide/run.py b/examples/vhdl/user_guide/run.py
index 87da8ffac..de6c1ef87 100644
--- a/examples/vhdl/user_guide/run.py
+++ b/examples/vhdl/user_guide/run.py
@@ -4,6 +4,14 @@
 #
 # Copyright (c) 2014-2019, Lars Asplund lars.anders.asplund@gmail.com
 
+"""
+VHDL User Guide
+---------------
+
+The most minimal VUnit VHDL project covering the basics of the
+:ref:`User Guide <user_guide>`.
+"""
+
 from os.path import join, dirname
 from vunit import VUnit
 
@@ -12,4 +20,6 @@
 ui = VUnit.from_argv()
 lib = ui.add_library("lib")
 lib.add_source_files(join(root, "*.vhd"))
-ui.main()
+
+if __name__ == '__main__':
+    ui.main()
diff --git a/examples/vhdl/vivado/run.py b/examples/vhdl/vivado/run.py
index ba3af6033..08ad72bee 100644
--- a/examples/vhdl/vivado/run.py
+++ b/examples/vhdl/vivado/run.py
@@ -4,6 +4,14 @@
 #
 # Copyright (c) 2014-2019, Lars Asplund lars.anders.asplund@gmail.com
 
+"""
+Vivado IP
+---------
+
+Demonstrates compiling and performing behavioral simulation of
+Vivado IPs with VUnit.
+"""
+
 from os.path import join, dirname
 from vunit import VUnit
 from vivado_util import add_vivado_ip
@@ -19,8 +27,9 @@
 tb_lib = ui.add_library("tb_lib")
 tb_lib.add_source_files(join(src_path, "test", "*.vhd"))
 
-add_vivado_ip(ui,
-              output_path=join(root, "vivado_libs"),
-              project_file=join(root, "myproject", "myproject.xpr"))
+if __name__ == '__main__':
+    add_vivado_ip(ui,
+                  output_path=join(root, "vivado_libs"),
+                  project_file=join(root, "myproject", "myproject.xpr"))
 
-ui.main()
+    ui.main()
diff --git a/tools/build_docs.py b/tools/build_docs.py
index 0436ab004..e7e324c2f 100644
--- a/tools/build_docs.py
+++ b/tools/build_docs.py
@@ -12,6 +12,7 @@
 from os.path import join, dirname
 import sys
 from create_release_notes import create_release_notes
+from docs_utils import examples
 
 
 def main():
@@ -19,6 +20,7 @@ def main():
     Build documentation/website
     """
     create_release_notes()
+    examples()
     check_call([sys.executable, "-m", "sphinx",
                 "-T", "-E", "-W", "-a", "-n", "-b", "html",
                 join(dirname(__file__), "..", "docs"), sys.argv[1]])
diff --git a/tools/docs_utils.py b/tools/docs_utils.py
new file mode 100644
index 000000000..f5f6f428a
--- /dev/null
+++ b/tools/docs_utils.py
@@ -0,0 +1,65 @@
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this file,
+# You can obtain one at http://mozilla.org/MPL/2.0/.
+#
+# Copyright (c) 2014-2019, Lars Asplund lars.anders.asplund@gmail.com
+
+"""
+Helper functions to generate examples.rst from docstrings in run.py files
+"""
+
+import sys
+import inspect
+from os.path import join, dirname, isdir
+from os import listdir
+
+
+ROOT = join(dirname(__file__), '..', 'docs')
+
+
+def examples():
+    """
+    Traverses the examples directory and generates examples.rst with the docstrings
+    """
+    eg_path = join(ROOT, '..', 'examples')
+    egs_fptr = open(join(ROOT, 'examples.rst'), "w+")
+    egs_fptr.write('\n'.join([
+        '.. _examples:\n',
+        'Examples',
+        '========',
+        '\n'
+    ]))
+    for language, subdir in {'VHDL': 'vhdl', 'SystemVerilog': 'verilog'}.items():
+        egs_fptr.write('\n'.join([
+            language,
+            '~~~~~~~~~~~~~~~~~~~~~~~',
+            '\n'
+        ]))
+        for item in listdir(join(eg_path, subdir)):
+            loc = join(eg_path, subdir, item)
+            if isdir(loc):
+                egs_fptr.write(_get_eg_doc(
+                    loc,
+                    'https://github.com/VUnit/vunit//tree/master/examples/' + item
+                ))
+
+
+def _get_eg_doc(location, ref):
+    """
+    Reads the docstring from a run.py file and rewrites the title to make it a ref
+    """
+    sys.path.append(location)
+    import run  # pylint: disable=import-error
+    vc_doc = inspect.getdoc(run)
+    del sys.modules['run']
+    sys.path.remove(location)
+    doc = ''
+    if vc_doc:
+        title = '`%s <%s/>`_' % (vc_doc.split('---', 1)[0][0:-1], ref)
+        doc = '\n'.join([
+            title,
+            '-' * len(title),
+            vc_doc.split('---\n', 1)[1],
+            '\n'
+        ])
+    return doc