add example instantiation to top of autogenerated output

Makefile

@@ -60,5 +60,8 @@ clean:
 	rm -rf dist/
 	rm -rf src/mantaray.egg-info
 
-loc:
-	find . -type f \( -iname \*.sv -o -iname \*.v -o -iname \*.py -o -iname \*.yaml -o -iname \*.md \) | sed 's/.*/"&"/' | xargs  wc -l
+total_loc:
+	find . -type f \( -iname \*.sv -o -iname \*.v -o -iname \*.py -o -iname \*.yaml -o -iname \*.yml -o -iname \*.md \) | sed 's/.*/"&"/' | xargs  wc -l
+
+real_loc:
+	find src test -type f \( -iname \*.sv -o -iname \*.v -o -iname \*.py -o -iname \*.yaml -o -iname \*.md \) | sed 's/.*/"&"/' | xargs  wc -l

src/manta/__init__.py

@@ -680,6 +680,57 @@ Provided under a GNU GPLv3 license. Go wild.
 */
 """
         return header
+    
+    def generate_ex_inst(self):
+        # this is a C-style block comment that contains an instantiation
+        # of the configured manta instance - the idea is that a user
+        # can copy-paste that into their design instead of trying to spot
+        # the difference between their code and the autogenerated code.
+
+        # hopefully this saves time!
+
+
+        # this turns a list like ['input wire foo', 'output reg bar'] into
+        # a nice string like ".foo(foo),\n .bar(bar)"
+        interface_ports = self.interface.hdl_top_level_ports()
+        interface_ports = [port.split(',')[0] for port in interface_ports]
+        interface_ports = [port.split(' ')[-1] for port in interface_ports]
+        interface_ports = [f".{port}({port})" for port in interface_ports] 
+        interface_ports = [f"    {port},\n" for port in interface_ports]
+        interface_ports = "".join(interface_ports) 
+
+        core_chain_ports = []
+        for core in self.cores:
+            ports = [port.split(',')[0] for port in core.hdl_top_level_ports()]
+            ports = [port.split(' ')[-1] for port in ports]
+            ports = [f".{port}({port})" for port in ports]
+            ports = [f"    {port},\n" for port in ports]
+            ports = "".join(ports)
+            ports = "\n" + ports
+            core_chain_ports.append(ports)
+
+        core_chain_ports = "\n".join(core_chain_ports)
+
+        ports = interface_ports + core_chain_ports
+
+        # remove trailing comma
+        ports = ports.rstrip()
+        if ports[-1] == ",":
+            ports = ports[:-1]
+        
+        return f"""
+/*
+
+// Here's an example instantiation of the Manta module you configured,
+// feel free to copy-paste this into your source!
+
+manta manta_inst (
+    .clk(clk),
+
+{ports});
+
+*/
+"""
 
     def generate_declaration(self):
         # get all the top level connections for each module.
@@ -762,6 +813,9 @@ module manta (
         # generate header
         header = self.generate_header()
 
+        # generate example instantiation
+        ex_inst = self.generate_ex_inst()
+
         # generate module declaration
         declar = self.generate_declaration()
 
@@ -781,7 +835,7 @@ module manta (
         module_defs = self.generate_module_defs()
 
         # assemble all the parts
-        hdl = header + declar + interface_rx + core_chain + interface_tx + footer
+        hdl = header + ex_inst + declar + interface_rx + core_chain + interface_tx + footer
         hdl += "\n /* ---- Module Definitions ----  */\n"
         hdl += module_defs