Add flatten option tests

This commit adds a basic test for the flatten option in the
verilog-diagram directive.

Signed-off-by: Robert Winkler <rwinkler@antmicro.com>

Author: rw1nkler

.travis.yml

@@ -22,6 +22,11 @@ jobs:
         - source env/conda/bin/activate sphinxcontrib-verilog-diagrams
         - cd tests && python3 -m unittest test.TestYosysScript
 
+      name: "Test :flatten: option"
+      script:
+        - source env/conda/bin/activate sphinxcontrib-verilog-diagrams
+        - cd tests && python3 -m unittest test.TestFlatten
+
     - stage: Tests
       name: "Test verilog_diagram_yosys config variable"
       script:

tests/test.py

@@ -190,5 +190,43 @@ def test_yosys_path(self):
             app = Sphinx(buildername="html", warningiserror=True, **sphinx_dirs)
             app.build(force_all=True)
 
+class TestFlatten(unittest.TestCase):
+
+    TEST_CASE_NAME = "TestFlatten"
+    TEST_CASE_BUILD_DIR = os.path.join("build", TEST_CASE_NAME)
+
+    def test_yosys_script(self):
+        TEST_NAME = "test_flatten"
+        TEST_BUILD_DIR = os.path.join("build", self.TEST_CASE_NAME, TEST_NAME)
+        TEST_FILES = [
+            "test_flatten/test_flatten.rst",
+            "verilog/fullAdder.v",
+            "verilog/halfAdder.v"
+        ]
+        TEST_JINJA_DICT = {
+            "verilog_diagrams_path": "'{}'".format(VERILOG_DIAGRAMS_PATH),
+            "master_doc": "'test_flatten'",
+            "custom_variables": ""
+        }
+
+        # Create the TestCase build directory
+        os.makedirs(TEST_BUILD_DIR, exist_ok=True)
+
+        # Generate a Sphinx config
+        generate_sphinx_config(TEST_BUILD_DIR, **TEST_JINJA_DICT)
+
+        # Copy the test files
+        for src in TEST_FILES:
+            src_basename = os.path.basename(src)
+            dst = os.path.join(TEST_BUILD_DIR, src_basename)
+            shutil.copyfile(src, dst)
+
+        # Run the Sphinx
+        sphinx_dirs = get_sphinx_dirs(TEST_BUILD_DIR)
+        with docutils_namespace():
+            app = Sphinx(buildername="html", warningiserror=True, **sphinx_dirs)
+            app.build(force_all=True)
+
+
 if __name__ == '__main__':
     unittest.main()

tests/test_flatten/test_flatten.rst

@@ -0,0 +1,119 @@
+Test Flatten Option
+===================
+
+This test checks whether the ``:flatten:`` option in the ``verilog-diagram``
+directive works as intended. The ``:flatten:`` option is used to resolve
+the black boxes created by Yosys in place of instantiated modules.
+With this option enabled Yosys will convert everything into low-level logic
+where only basic logic cells and basic FPGA primitives will be used.
+
+Netlistsvg Diagram
+------------------
+
+Here is the diagram of a half-adder with its RST code::
+
+   .. verilog-diagram:: halfAdder.v
+      :type: netlistsvg
+      :module: halfAdder
+
+.. verilog-diagram:: halfAdder.v
+   :type: netlistsvg
+   :module: halfAdder
+
+The diagram below has been created without the ``:flatten:`` option::
+
+   .. verilog-diagram:: fullAdder.v
+      :type: netlistsvg
+      :module: fullAdder
+
+.. verilog-diagram:: fullAdder.v
+   :type: netlistsvg
+   :module: fullAdder
+
+The diagram below has been created using the ``:flatten:`` option.
+You can see that the ``halfAdder`` black box is substituted by the appropriate
+logic elements::
+
+   .. verilog-diagram:: fullAdder.v
+      :type: netlistsvg
+      :module: fullAdder
+      :flatten:
+
+.. verilog-diagram:: fullAdder.v
+   :type: netlistsvg
+   :module: fullAdder
+   :flatten:
+
+Yosys BlackBox Diagram
+----------------------
+
+Here is the diagram of a half-adder with its RST code::
+
+   .. verilog-diagram:: halfAdder.v
+      :type: yosys-blackbox
+      :module: halfAdder
+
+.. verilog-diagram:: halfAdder.v
+   :type: yosys-blackbox
+   :module: halfAdder
+
+The diagram below has been created without the ``:flatten:`` option::
+
+   .. verilog-diagram:: fullAdder.v
+      :type: yosys-blackbox
+      :module: fullAdder
+
+.. verilog-diagram:: fullAdder.v
+   :type: yosys-blackbox
+   :module: fullAdder
+
+The diagram below has been created using the ``:flatten:`` option.
+You can see that the ``halfAdder`` black box is substituted by the appropriate
+logic elements::
+
+   .. verilog-diagram:: fullAdder.v
+      :type: yosys-blackbox
+      :module: fullAdder
+      :flatten:
+
+.. verilog-diagram:: fullAdder.v
+   :type: yosys-blackbox
+   :module: fullAdder
+   :flatten:
+
+Yosys AIG Diagram
+-----------------
+
+Here is the diagram of a half-adder with its RST code::
+
+   .. verilog-diagram:: halfAdder.v
+      :type: yosys-aig
+      :module: halfAdder
+
+.. verilog-diagram:: halfAdder.v
+   :type: yosys-aig
+   :module: halfAdder
+
+The diagram below has been created without the ``:flatten:`` option::
+
+   .. verilog-diagram:: fullAdder.v
+      :type: yosys-aig
+      :module: fullAdder
+
+.. verilog-diagram:: fullAdder.v
+   :type: yosys-aig
+   :module: fullAdder
+
+The diagram below has been created using the ``:flatten:`` option.
+You can see that the ``halfAdder`` black box is substituted by the appropriate
+logic elements::
+
+   .. verilog-diagram:: fullAdder.v
+      :type: yosys-aig
+      :module: fullAdder
+      :flatten:
+
+.. verilog-diagram:: fullAdder.v
+   :type: yosys-aig
+   :module: fullAdder
+   :flatten:

tests/verilog/fullAdder.v

@@ -0,0 +1,14 @@
+`include "halfAdder.v"
+
+module fullAdder (
+  output wire cout, s,
+  input wire cin, x, y
+);
+  wire c1, c2, s1;
+
+  halfAdder h1(c1, s1, x, y);
+  halfAdder h2(c2, s, cin, s1);
+
+  assign cout = c1 | c2;
+
+endmodule

tests/verilog/halfAdder.v

@@ -0,0 +1,9 @@
+module halfAdder (
+  output wire c, s,
+  input wire x, y
+);
+
+  assign s = x ^ y;
+  assign c = x & y;
+
+endmodule