feat(docs): generate docs/examples.rst automatically from docstrings

.gitignore

@@ -1,2 +1,4 @@
 **/vunit_out
-*.pyc
+*.pyc
+docs/examples.rst
+docs/release_notes.rst

docs/documentation.rst

@@ -7,5 +7,6 @@ Documentation
    cli
    python_interface
    vhdl_libraries
+   examples
 
 * :ref:`genindex`

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.

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()

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()

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()

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()

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()

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()

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()

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()

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()

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)

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()

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()

examples/vhdl/logging/run.py

@@ -4,11 +4,19 @@
 #
 # 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
 
 ui = VUnit.from_argv()
 lib = ui.add_library("lib")
 lib.add_source_files(join(dirname(__file__), "*.vhd"))
 
-ui.main()
+if __name__ == '__main__':
+    ui.main()

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()

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()