diff --git a/README.md b/README.md
deleted file mode 100644
index eceb48e..0000000
--- a/README.md
+++ /dev/null
@@ -1,99 +0,0 @@
-# python-symbiflow-v2x
-
-[![Documentation Status](https://readthedocs.org/projects/python-symbiflow-v2x/badge/?version=latest)](https://python-symbiflow-v2x.readthedocs.io/en/latest/?badge=latest) [![Build Status](https://travis-ci.com/SymbiFlow/python-symbiflow-v2x.svg?branch=master)](https://travis-ci.com/SymbiFlow/python-symbiflow-v2x)
-
-Tool for converting specialized annotated Verilog models into XML needed for
-[Verilog to Routing flow](https://docs.verilogtorouting.org/en/latest/arch/reference/).
-
-Documentation can be found at https://python-symbiflow-v2x.readthedocs.io/en/latest/
-
-## Installation
-v2x can be installed from a local git repository using pip.
-
-```
-cd python-symbiflow-v2x
-pip install .
-```
-
-Alternatively, it can be installed from GitHub directly.
-
-```
-pip install git+https://github.com/SymbiFlow/python-symbiflow-v2x.git
-```
-
-## Usage
-After installing v2x, you can run `v2x` to use it.
-
-```
-v2x -h
-usage: __main__.py [-h] [--top TOP] [--outfile OUTFILE] [--includes INCLUDES]
-                   [--mode {pb_type,model}]
-                   input.v [input.v ...]
-
-Verilog to XML
-
-positional arguments:
-  input.v               One or more Verilog input files, that will be passed
-                        to Yosys internally. They should be enough to generate
-                        a flattened representation of the model, so that paths
-                        through the model can be determined.
-
-optional arguments:
-  -h, --help            show this help message and exit
-  --top TOP             Top level module, will usually be automatically
-                        determined from the file name im.v
-  --outfile OUTFILE, -o OUTFILE
-                        Output filename, default 'output.xml'
-  --includes INCLUDES   Comma separate list of include directories.
-  --mode {pb_type,model}
-                        Output file type, possible values are: pb_type and
-                        model. Default value is pb_type
-```
-
-For example, to generate a pb_type xml file from adder.v, run 
-
-```
-v2x -o adder.pb_type.xml adder.v
-```
-
-Or, to generate a model xml file, run 
-
-```
-v2x --mode model -o adder.model.xml adder.v
-```
-
-v2x expects the module name to be the same as the file name. If it is different, make sure to specifiy it with the `--top` argument.
-
-```
-v2x --top BLOCK -o adder.pb_type.xml adder.v
-```
-
-## Tests
-The test cases are stored in tests/, and pytest can be used to run them.
-
-```
-rm -rf build  # run this step so that pytest uses the latest files for the tests
-pytest -vv
-```
-
-If you are making changes to any python code, make sure that they follow the PEP8 style guide by running flake8.
-
-```
-flake8 tests
-flake8 v2x
-```
-
-## Documentation
-We use sphinx for our documentation and the files are stored in docs/. To host it locally (if you are planning to update it), you can use the Makefile inside.
-
-First, run `make env` to prepare a Conda environment that contains the necessary packages to build and host the documentation site. After that, simply run `make livehtml` which starts a local server running at port 8000 with the documentation site.
-
-```
-cd docs
-make env
-make livehtml
-```
-
-## Talks
-
-[![v2x orconf talk](https://img.youtube.com/vi/a31vH_tZLBM/0.jpg)](https://www.youtube.com/watch?v=a31vH_tZLBM)
\ No newline at end of file
diff --git a/README.rst b/README.rst
index b2a5f86..7f43e37 100644
--- a/README.rst
+++ b/README.rst
@@ -1,5 +1,5 @@
-SymbiFlow Verilog to VtR XML (v2x)
-===================================
+Verilog to Routing XML file generation from Verilog (`python-symbiflow-v2x`)
+=============================================================================
 
 
 .. image:: https://readthedocs.org/projects/python-symbiflow-v2x/badge/?version=latest
diff --git a/docs/.gitignore b/docs/.gitignore
index c97efb9..c249d4a 100644
--- a/docs/.gitignore
+++ b/docs/.gitignore
@@ -1,5 +1,5 @@
 env
 _build
-tests/**/*.md
-tests/**/*.svg
-tests/**/*.png
+examples/**/*.md
+examples/**/*.svg
+examples/**/*.png
diff --git a/docs/Makefile b/docs/Makefile
index d4a3bc0..e0fbd13 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -15,7 +15,7 @@
 # You can set these variables from the command line.
 SPHINXOPTS      =
 SPHINXBUILD     = [ -e env/bin/activate ] && source env/bin/activate; sphinx-build
-SPHINXAUTOBUILD = [ -e env/bin/activate ] && source env/bin/activate; sphinx-autobuild
+SPHINXAUTOBUILD = [ -e env/bin/activate ] && source env/bin/activate; sphinx-autobuild --watch $(MAKEDIR)../tests
 SPHINXPROJ      = SymbiFlowV2X
 SOURCEDIR       = .
 BUILDDIR        = _build
@@ -62,9 +62,9 @@
 
 # Update fuzzer / minitest markdown links.
 tests-links:
-	@mkdir -p $(MAKEDIR)/tests
-	@cd $(MAKEDIR)/tests && find -name '*.md' -delete && find -type d -empty -delete
-	@cd $(MAKEDIR)/tests && \
+	@mkdir -p $(MAKEDIR)/examples
+	@cd $(MAKEDIR)/examples && find -name '*.md' -delete && find -type d -empty -delete
+	@cd $(MAKEDIR)/examples && \
 		for I in $$(cd ../../tests/ ; find -name '*.md' | sort); do \
 			F=$$(dirname $$I); D=$$(dirname $$F); N=$$(basename $$F); \
 			S=../../tests/$$I; O=$$D/$$N.md; \
@@ -73,7 +73,7 @@
 			fi; \
 			ln -sf $$(realpath $$S --relative-to=$$D) $$O; \
 		done
-	@cd $(MAKEDIR)/tests && \
+	@cd $(MAKEDIR)/examples && \
 		for I in $$(cd ../../tests/ ; find -name '*.svg' -o -name '*.png' | sort); do \
 			F=$$(dirname $$I); D=$$(dirname $$F); N=$$(basename $$I); \
 			S=../../tests/$$I; O=$$D/$$N; \
diff --git a/docs/environment.yml b/docs/environment.yml
index c219d35..794b84c 100644
--- a/docs/environment.yml
+++ b/docs/environment.yml
@@ -14,8 +14,7 @@
 # ReadTheDoc dependencies
 - mock
 - pillow
-- sphinx
-- sphinx_rtd_theme
+- sphinx=2.4.4
 # Packages installed from PyPI
 - pip:
   - -r file:requirements.txt
diff --git a/docs/examples.rst b/docs/examples.rst
new file mode 100644
index 0000000..158bdd3
--- /dev/null
+++ b/docs/examples.rst
@@ -0,0 +1,10 @@
+Examples
+========
+
+Here we have examples on how v2x converts a Verilog module to its corresponding model.xml and pb_type.xml files. These examples are taken from the `v2x test cases <https://github.com/SymbiFlow/python-symbiflow-v2x/tree/master/tests>`_.
+
+.. toctree::
+
+   examples/clocks.rst
+   examples/dsp.rst
+   examples/vtr-examples.rst
\ No newline at end of file
diff --git a/docs/examples/clocks.rst b/docs/examples/clocks.rst
new file mode 100644
index 0000000..fc6adc5
--- /dev/null
+++ b/docs/examples/clocks.rst
@@ -0,0 +1,12 @@
+.. Clock Example Tests
+
+Clock
+=====
+
+There are various ways for an input or output port to be detected as a clock by v2x. Here are examples on ways to do so.
+
+.. toctree::
+   clocks/autodetection.rst
+   clocks/manual_input.rst
+   clocks/manual_output.rst
+   clocks/multiple.rst
diff --git a/docs/examples/clocks/autodetection.rst b/docs/examples/clocks/autodetection.rst
new file mode 100644
index 0000000..789cf52
--- /dev/null
+++ b/docs/examples/clocks/autodetection.rst
@@ -0,0 +1,6 @@
+Autodetection of clock from flipflop
+====================================
+
+.. include:: ../../../tests/clocks/dff_one_clock/README.rst
+.. include:: ../../../tests/clocks/dff_comb_one_clock/README.rst
+.. include:: ../../../tests/clocks/dff_two_clocks/README.rst
diff --git a/docs/examples/clocks/manual_input.rst b/docs/examples/clocks/manual_input.rst
new file mode 100644
index 0000000..a5d6b39
--- /dev/null
+++ b/docs/examples/clocks/manual_input.rst
@@ -0,0 +1,7 @@
+Manually set inputs as clock
+============================
+
+.. include:: ../../../tests/clocks/input_attr_clock/README.rst
+.. include:: ../../../tests/clocks/input_attr_not_clock/README.rst
+.. include:: ../../../tests/clocks/input_named_clk/README.rst
+.. include:: ../../../tests/clocks/input_named_regex/README.rst
diff --git a/docs/examples/clocks/manual_output.rst b/docs/examples/clocks/manual_output.rst
new file mode 100644
index 0000000..39e7894
--- /dev/null
+++ b/docs/examples/clocks/manual_output.rst
@@ -0,0 +1,5 @@
+Manually set outputs as clock
+=============================
+
+.. include:: ../../../tests/clocks/output_attr_clock/README.rst
+.. include:: ../../../tests/clocks/output_named_clk/README.rst
diff --git a/docs/examples/clocks/multiple.rst b/docs/examples/clocks/multiple.rst
new file mode 100644
index 0000000..596ad4b
--- /dev/null
+++ b/docs/examples/clocks/multiple.rst
@@ -0,0 +1,5 @@
+Multiple clocks
+===============
+
+.. include:: ../../../tests/clocks/multiple_inputs_named_clk/README.rst
+.. include:: ../../../tests/clocks/multiple_outputs_named_clk/README.rst
diff --git a/docs/tests/dsp.rst b/docs/examples/dsp.rst
similarity index 90%
rename from docs/tests/dsp.rst
rename to docs/examples/dsp.rst
index 6fb30c7..408007b 100644
--- a/docs/tests/dsp.rst
+++ b/docs/examples/dsp.rst
@@ -1,7 +1,7 @@
 .. DSP Based Example Tests
 
-DSP Examples
-============
+DSP
+===
 
 .. toctree::
 
diff --git a/docs/tests/vtr-examples.rst b/docs/examples/vtr-examples.rst
similarity index 79%
rename from docs/tests/vtr-examples.rst
rename to docs/examples/vtr-examples.rst
index 33e94d9..aef1d74 100644
--- a/docs/tests/vtr-examples.rst
+++ b/docs/examples/vtr-examples.rst
@@ -1,7 +1,7 @@
 .. Examples from the Verilog to Routing documentation / tutorials.
 
-Verilog to Routing Examples
-===========================
+Verilog to Routing
+==================
 
 Primitive Block Timing Modeling Tutorial
 ----------------------------------------
diff --git a/docs/index.rst b/docs/index.rst
index d950667..6c144c0 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -5,12 +5,4 @@
    :glob:
    :hidden:
 
-   tests/vtr-examples.rst
-   tests/dsp.rst
-
-.. toctree::
-   :maxdepth: 3
-   :glob:
-   :hidden:
-
-   tests/clocks.rst
\ No newline at end of file
+   examples.rst
diff --git a/docs/requirements.txt b/docs/requirements.txt
index eb5a223..4e1216a 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1,10 +1,8 @@
 git+http://github.com/SymbiFlow/sphinx_materialdesign_theme.git@master#egg=sphinx_symbiflow_theme
 
 docutils
-sphinx
 sphinx-autobuild
 
-breathe
 recommonmark
 sphinx-markdown-tables
 sphinxcontrib-napoleon
diff --git a/docs/tests/clocks.rst b/docs/tests/clocks.rst
deleted file mode 100644
index 68e741b..0000000
--- a/docs/tests/clocks.rst
+++ /dev/null
@@ -1,40 +0,0 @@
-.. Clock Example Tests
-
-Clock Examples
-==============
-
-Autodetection clock from flipflop
----------------------------------
-
-.. toctree::
-
-   clocks/dff_one_clock.md
-   clocks/dff_two_clocks.md
-
-.. include:: ../../tests/clocks/dff_comb_one_clock/README.rst
-
-Manual Input Clock
-------------------
-
-.. toctree::
-
-   clocks/input_attr_clock.md
-   clocks/input_named_clk.md
-   clocks/input_named_rdclk.md
-
-Manual Output Clock
--------------------
-
-.. toctree::
-
-   clocks/output_attr_clock.md
-   clocks/output_named_clk.md
-   clocks/output_named_rdclk.md
-
-Multiple Clocks
----------------
-
-.. toctree::
-
-   clocks/multiple_inputs_named_clk.md
-   clocks/multiple_outputs_named_clk.md
diff --git a/tests/clocks/dff_comb_one_clock/README.rst b/tests/clocks/dff_comb_one_clock/README.rst
index d1bcf97..ab01cc6 100644
--- a/tests/clocks/dff_comb_one_clock/README.rst
+++ b/tests/clocks/dff_comb_one_clock/README.rst
@@ -1,9 +1,23 @@
 D-Flipflop with combinational logic
 +++++++++++++++++++++++++++++++++++
 
-`input wire a` should be detected as a clock because it drives the flip flop.
+The following shows a combinational logic design driven by a clock. ``input wire a`` should be detected as a clock because it drives the flip flop.
 
-.. symbolator:: ../../tests/clocks/dff_comb_one_clock/dff_comb_one_clock.sim.v
+.. symbolator:: ../../../tests/clocks/dff_comb_one_clock/dff_comb_one_clock.sim.v
 
-.. literalinclude:: ../../tests/clocks/dff_comb_one_clock/dff_comb_one_clock.sim.v
+.. verilog-diagram:: ../../../tests/clocks/dff_comb_one_clock/dff_comb_one_clock.sim.v
+   :type: netlistsvg
+   :module: BLOCK
+
+|
+
+.. literalinclude:: ../../../tests/clocks/dff_comb_one_clock/dff_comb_one_clock.sim.v
    :language: verilog
+   :start-after:  */
+   :caption: tests/clocks/dff_comb_one_clock/dff_comb_one_clock.sim.v
+
+The ``is_clock`` attribute of the ``a`` port is set to 1, and the ports ``b``, ``c`` and ``d`` have their ``clock`` attribute set to ``a``.
+
+.. literalinclude:: ../../../tests/clocks/dff_comb_one_clock/golden.model.xml
+   :language: xml
+   :caption: tests/clocks/dff_comb_one_clock/golden.model.xml
\ No newline at end of file
diff --git a/tests/clocks/dff_one_clock/README.rst b/tests/clocks/dff_one_clock/README.rst
new file mode 100644
index 0000000..4acbb70
--- /dev/null
+++ b/tests/clocks/dff_one_clock/README.rst
@@ -0,0 +1,23 @@
+D-Flipflop with one clock
++++++++++++++++++++++++++
+
+The following shows a simple D-flip flop driven by one clock. ``input wire a`` should be detected as a clock because it drives the flip flop.
+
+.. symbolator:: ../../../tests/clocks/dff_one_clock/dff_one_clock.sim.v
+
+.. verilog-diagram:: ../../../tests/clocks/dff_one_clock/dff_one_clock.sim.v
+   :type: netlistsvg
+   :module: BLOCK
+
+|
+
+.. literalinclude:: ../../../tests/clocks/dff_one_clock/dff_one_clock.sim.v
+   :language: verilog
+   :start-after: */
+   :caption: tests/clocks/dff_one_clock/dff_one_clock.sim.v
+
+As you can see in the generated model, the ``is_clock`` attribute of the ``a`` port is set to 1, while the ``b`` and ``c`` ports have their ``clock`` attribute set to ``a``.
+
+.. literalinclude:: ../../../tests/clocks/dff_one_clock/golden.model.xml
+   :language: xml
+   :caption: tests/clocks/dff_one_clock/golden.model.xml
diff --git a/tests/clocks/dff_two_clocks/README.rst b/tests/clocks/dff_two_clocks/README.rst
new file mode 100644
index 0000000..86a9fa7
--- /dev/null
+++ b/tests/clocks/dff_two_clocks/README.rst
@@ -0,0 +1,23 @@
+D-Flipflop with two clocks
+++++++++++++++++++++++++++
+
+``input wire c1`` and ``input wire c2`` should be detected as clocks because they drive the flip flop.
+
+.. symbolator:: ../../../tests/clocks/dff_two_clocks/dff_two_clocks.sim.v
+
+.. verilog-diagram:: ../../../tests/clocks/dff_two_clocks/dff_two_clocks.sim.v
+   :type: netlistsvg
+   :module: BLOCK
+
+|
+
+.. literalinclude:: ../../../tests/clocks/dff_two_clocks/dff_two_clocks.sim.v
+   :language: verilog
+   :start-after: */
+   :caption: tests/clocks/dff_two_clocks/dff_two_clocks.sim.v
+
+The ``is_clock`` attribute of the ``c1`` and ``c2`` ports are set to 1, and the ports ``a``, ``b``, ``c``, ``o1`` and ``o2`` have their ``clock`` attribute set to the respective clocks they are driven by.
+
+.. literalinclude:: ../../../tests/clocks/dff_two_clocks/golden.model.xml
+   :language: xml
+   :caption: tests/clocks/dff_two_clocks/golden.model.xml
diff --git a/tests/clocks/dff_two_clocks/golden.model.xml b/tests/clocks/dff_two_clocks/golden.model.xml
index 1ca3456..c6afb90 100644
--- a/tests/clocks/dff_two_clocks/golden.model.xml
+++ b/tests/clocks/dff_two_clocks/golden.model.xml
@@ -2,11 +2,11 @@
 <models>
   <model name="BLOCK">
     <input_ports>
-      <port clock="c1" combinational_sink_ports="o1" name="a"/>
-      <port clock="c2 c1" combinational_sink_ports="o2 o1" name="b"/>
-      <port clock="c2" combinational_sink_ports="o2" name="c"/>
-      <port is_clock="1" name="c1"/>
-      <port is_clock="1" name="c2"/>
+      <port name="a" combinational_sink_ports="o1" clock="c1"/>
+      <port name="b" combinational_sink_ports="o2 o1" clock="c2 c1"/>
+      <port name="c" combinational_sink_ports="o2" clock="c2"/>
+      <port name="c1" is_clock="1"/>
+      <port name="c2" is_clock="1"/>
     </input_ports>
     <output_ports>
       <port clock="c1" name="o1"/>
diff --git a/tests/clocks/input_attr_clock/README.rst b/tests/clocks/input_attr_clock/README.rst
new file mode 100644
index 0000000..792c0ff
--- /dev/null
+++ b/tests/clocks/input_attr_clock/README.rst
@@ -0,0 +1,19 @@
+Manually set input as clock by setting the CLOCK attribute
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+The following shows that ``input wire a`` is given the ``(* CLOCK *)`` attribute.
+
+.. symbolator:: ../../../tests/clocks/input_attr_clock/input_attr_clock.sim.v
+
+|
+
+.. literalinclude:: ../../../tests/clocks/input_attr_clock/input_attr_clock.sim.v
+   :language: verilog
+   :start-after: */
+   :caption: tests/clocks/input_attr_clock/input_attr_clock.sim.v
+
+As such, the ``is_clock`` attribute of the ``a`` port is set to 1.
+
+.. literalinclude:: ../../../tests/clocks/input_attr_clock/golden.model.xml
+   :language: xml
+   :caption: tests/clocks/input_attr_clock/golden.model.xml
\ No newline at end of file
diff --git a/tests/clocks/input_attr_not_clock/README.rst b/tests/clocks/input_attr_not_clock/README.rst
new file mode 100644
index 0000000..b2404e1
--- /dev/null
+++ b/tests/clocks/input_attr_not_clock/README.rst
@@ -0,0 +1,27 @@
+Force input as regular input by setting the CLOCK attribute
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+``input wire a`` should be detected as a clock because it drives the flip flop. However, it has the attribute CLOCK set to 0 which should force it to be a regular input.
+
+.. symbolator:: ../../../tests/clocks/input_attr_not_clock/block.sim.v
+
+.. verilog-diagram:: ../../../tests/clocks/input_attr_not_clock/block.sim.v
+   :type: netlistsvg
+   :module: BLOCK
+
+|
+
+.. literalinclude:: ../../../tests/clocks/input_attr_not_clock/block.sim.v
+   :language: verilog
+   :start-after: */
+   :caption: tests/clocks/input_attr_not_clock/block.sim.v
+
+As such, the ``is_clock`` attribute of the ``a`` port is not set.
+
+.. literalinclude:: ../../../tests/clocks/input_attr_not_clock/golden.model.xml
+   :language: xml
+   :caption: tests/clocks/input_attr_not_clock/golden.model.xml
+
+.. literalinclude:: ../../../tests/clocks/input_attr_not_clock/golden.pb_type.xml
+   :language: xml
+   :caption: tests/clocks/input_attr_not_clock/golden.pb_type.xml
\ No newline at end of file
diff --git a/tests/clocks/input_named_clk/README.rst b/tests/clocks/input_named_clk/README.rst
new file mode 100644
index 0000000..ef83375
--- /dev/null
+++ b/tests/clocks/input_named_clk/README.rst
@@ -0,0 +1,19 @@
+Set input as clock by name (clk)
+++++++++++++++++++++++++++++++++
+
+An input wire can be set as a clock by assigning ``clk`` as its name.
+
+.. symbolator:: ../../../tests/clocks/input_named_clk/input_named_clk.sim.v
+
+|
+
+.. literalinclude:: ../../../tests/clocks/input_named_clk/input_named_clk.sim.v
+   :language: verilog
+   :start-after: */
+   :caption: tests/clocks/input_named_clk/input_named_clk.sim.v
+
+As such, the ``is_clock`` attribute of the ``clk`` port is set to 1, without needing to set anything else in the verilog code.
+
+.. literalinclude:: ../../../tests/clocks/input_named_clk/golden.model.xml
+   :language: xml
+   :caption: tests/clocks/input_named_clk/golden.model.xml
\ No newline at end of file
diff --git a/tests/clocks/input_named_regex/README.rst b/tests/clocks/input_named_regex/README.rst
new file mode 100644
index 0000000..fd46a7b
--- /dev/null
+++ b/tests/clocks/input_named_regex/README.rst
@@ -0,0 +1,23 @@
+Set input as clock by name (regex)
+++++++++++++++++++++++++++++++++++
+
+An input wire can be set as a clock by having ``clk`` in its name (case insensitive).
+
+.. symbolator:: ../../../tests/clocks/input_named_regex/block.sim.v
+
+|
+
+.. literalinclude:: ../../../tests/clocks/input_named_regex/block.sim.v
+   :language: verilog
+   :start-after: */
+   :caption: tests/clocks/input_named_regex/block.sim.v
+
+As such, the ``is_clock`` attribute of wires with a variation of ``clk`` in their name is set to 1.
+
+.. literalinclude:: ../../../tests/clocks/input_named_regex/golden.model.xml
+   :language: xml
+   :caption: tests/clocks/input_named_regex/golden.model.xml
+
+.. literalinclude:: ../../../tests/clocks/input_named_regex/golden.pb_type.xml
+   :language: xml
+   :caption: tests/clocks/input_named_regex/golden.pb_type.xml
\ No newline at end of file
diff --git a/tests/clocks/multiple_inputs_named_clk/README.rst b/tests/clocks/multiple_inputs_named_clk/README.rst
new file mode 100644
index 0000000..b71f1d1
--- /dev/null
+++ b/tests/clocks/multiple_inputs_named_clk/README.rst
@@ -0,0 +1,19 @@
+Set inputs as clock by name (multiple clock inputs)
++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+``input wire rdclk`` and ``input wire wrclk`` have ``clk`` in their names, hence are recognized as clock inputs by v2x.
+
+.. symbolator:: ../../../tests/clocks/multiple_inputs_named_clk/multiple_inputs_named_clk.sim.v
+
+|
+
+.. literalinclude:: ../../../tests/clocks/multiple_inputs_named_clk/multiple_inputs_named_clk.sim.v
+   :language: verilog
+   :start-after: */
+   :caption: tests/clocks/multiple_inputs_named_clk/multiple_inputs_named_clk.sim.v
+
+As such, the ``is_clock`` attribute of the ``rdclk`` and ``wrclk`` ports are set to 1.
+
+.. literalinclude:: ../../../tests/clocks/multiple_inputs_named_clk/golden.model.xml
+   :language: xml
+   :caption: tests/clocks/multiple_inputs_named_clk/golden.model.xml
\ No newline at end of file
diff --git a/tests/clocks/multiple_outputs_named_clk/README.rst b/tests/clocks/multiple_outputs_named_clk/README.rst
new file mode 100644
index 0000000..fc00979
--- /dev/null
+++ b/tests/clocks/multiple_outputs_named_clk/README.rst
@@ -0,0 +1,19 @@
+Set outputs as clock by name (multiple clock outputs)
++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+``output wire rdclk`` and ``output wire wrclk`` have ``clk`` in their names, hence are recognized as clock inputs by v2x.
+
+.. symbolator:: ../../../tests/clocks/multiple_outputs_named_clk/multiple_outputs_named_clk.sim.v
+
+|
+
+.. literalinclude:: ../../../tests/clocks/multiple_outputs_named_clk/multiple_outputs_named_clk.sim.v
+   :language: verilog
+   :start-after: */
+   :caption: tests/clocks/multiple_outputs_named_clk/multiple_outputs_named_clk.sim.v
+
+As such, the ``is_clock`` attribute of the ``rdclk`` and ``wrclk`` ports are set to 1.
+
+.. literalinclude:: ../../../tests/clocks/multiple_outputs_named_clk/golden.model.xml
+   :language: xml
+   :caption: tests/clocks/multiple_outputs_named_clk/golden.model.xml
\ No newline at end of file
diff --git a/tests/clocks/output_attr_clock/README.rst b/tests/clocks/output_attr_clock/README.rst
new file mode 100644
index 0000000..7e8b221
--- /dev/null
+++ b/tests/clocks/output_attr_clock/README.rst
@@ -0,0 +1,19 @@
+Manually set output as clock by setting the CLOCK attribute
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+The following shows that ``output wire o`` is given the ``(* CLOCK *)`` attribute.
+
+.. symbolator:: ../../../tests/clocks/output_attr_clock/output_attr_clock.sim.v
+
+|
+
+.. literalinclude:: ../../../tests/clocks/output_attr_clock/output_attr_clock.sim.v
+   :language: verilog
+   :start-after: */
+   :caption: tests/clocks/output_attr_clock/output_attr_clock.sim.v
+
+As such, the ``is_clock`` attribute of the ``o`` port is set to 1.
+
+.. literalinclude:: ../../../tests/clocks/output_attr_clock/golden.model.xml
+   :language: xml
+   :caption: tests/clocks/output_attr_clock/golden.model.xml
\ No newline at end of file
diff --git a/tests/clocks/output_named_clk/README.rst b/tests/clocks/output_named_clk/README.rst
new file mode 100644
index 0000000..f859e8b
--- /dev/null
+++ b/tests/clocks/output_named_clk/README.rst
@@ -0,0 +1,19 @@
+Set output as clock by name (clk)
++++++++++++++++++++++++++++++++++
+
+An output wire can be set as a clock by assigning ``clk`` as its name.
+
+.. symbolator:: ../../../tests/clocks/output_named_clk/output_named_clk.sim.v
+
+|
+
+.. literalinclude:: ../../../tests/clocks/output_named_clk/output_named_clk.sim.v
+   :language: verilog
+   :start-after: */
+   :caption: tests/clocks/output_named_clk/output_named_clk.sim.v
+
+As such, the ``is_clock`` attribute of the ``clk`` output port is set to 1.
+
+.. literalinclude:: ../../../tests/clocks/output_named_clk/golden.model.xml
+   :language: xml
+   :caption: tests/clocks/output_named_clk/golden.model.xml
\ No newline at end of file