diff --git a/CARAVEL_USER.md b/docs/source/README.md
similarity index 100%
rename from CARAVEL_USER.md
rename to docs/source/README.md
diff --git a/docs/source/README.rst b/docs/source/README.rst
deleted file mode 100644
index ac86bf8..0000000
--- a/docs/source/README.rst
+++ /dev/null
@@ -1,269 +0,0 @@
-.. raw:: html
-
-   <!---
-   # SPDX-FileCopyrightText: 2020 Efabless Corporation
-   #
-   # Licensed under the Apache License, Version 2.0 (the "License");
-   # you may not use this file except in compliance with the License.
-   # You may obtain a copy of the License at
-   #
-   #      http://www.apache.org/licenses/LICENSE-2.0
-   #
-   # Unless required by applicable law or agreed to in writing, software
-   # distributed under the License is distributed on an "AS IS" BASIS,
-   # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-   # See the License for the specific language governing permissions and
-   # limitations under the License.
-   #
-   # SPDX-License-Identifier: Apache-2.0
-   -->
-
-Caravel User Project
-====================
-
-|License| |User CI| |Caravel Build|
-
-Table of contents
-=================
-
--  `Overview <#overview>`__
--  `Install Caravel <#install-caravel>`__
--  `Caravel Integration <#caravel-integration>`__
-
-   -  `Repo Integration <#repo-integration>`__
-   -  `Verilog Integration <#verilog-integration>`__
-
--  `Running Full Chip Simulation <#running-full-chip-simulation>`__
--  `Hardening the User Project Macro using
-   Openlane <#hardening-the-user-project-macro-using-openlane>`__
--  `Checklist for Open-MPW
-   Submission <#checklist-for-open-mpw-submission>`__
-
-Overview
-========
-
-This repo contains a sample user project that utilizes the
-`caravel <https://github.com/efabless/caravel.git>`__ chip user space.
-The user project is a simple counter that showcases how to make use of
-`caravel's <https://github.com/efabless/caravel.git>`__ user space
-utilities like IO pads, logic analyzer probes, and wishbone port. The
-repo also demonstrates the recommended structure for the open-mpw
-shuttle projects.
-
-Install Caravel
-===============
-
-To setup caravel, run the following:
-
-.. code:: bash
-
-    # By default, CARAVEL_ROOT is set to $(pwd)/caravel
-    # If you want to install caravel at a different location, run "export CARAVEL_ROOT=<caravel-path>"
-    # Disable submodule installation if needed by, run "export SUBMODULE=0"
-
-    make install
-
-To update the installed caravel to the latest, run:
-
-.. code:: bash
-
-     make update_caravel
-
-To remove caravel, run
-
-.. code:: bash
-
-    make uninstall
-
-By default
-`caravel-lite <https://github.com/efabless/caravel-lite.git>`__ is
-installed. To install the full version of caravel, run this prior to
-calling make install.
-
-.. code:: bash
-
-    export CARAVEL_LITE=0
-
-Caravel Integration
-===================
-
-Repo Integration
-----------------
-
-Caravel files are kept separate from the user project by having caravel
-as submodule. The submodule commit should point to the latest of
-caravel/caravel-lite master. The following files should have a symbolic
-link to `caravel's <https://github.com/efabless/caravel.git>`__
-corresponding files:
-
--  `Openlane Makefile <openlane/Makefile>`__: This provides an easier
-   way for running openlane to harden your macros. Refer to `Hardening
-   the User Project Macro using
-   Openlane <#hardening-the-user-project-macro-using-openlane>`__. Also,
-   the makefile retains the openlane summary reports under the signoff
-   directory.
-
--  `Pin order <openlane/user_project_wrapper/pin_order.cfg>`__ file for
-   the user wrapper: The hardened user project wrapper macro must have
-   the same pin order specified in caravel's repo. Failing to adhere to
-   the same order will fail the gds integration of the macro with
-   caravel's back-end.
-
-The symbolic links are automatically set when you run ``make install``.
-
-Verilog Integration
--------------------
-
-You need to create a wrapper around your macro that adheres to the
-template at
-`user\_project\_wrapper <caravel/verilog/rtl/__user_project_wrapper.v>`__.
-The wrapper top module must be named ``user_project_wrapper`` and must
-have the same input and output ports. The wrapper gives access to the
-user space utilities provided by caravel like IO ports, logic analyzer
-probes, and wishbone bus connection to the management SoC.
-
-For this sample project, the user macro makes use of:
-
--  The IO ports for displaying the count register values on the IO pads.
-
--  The LA probes for supplying an optional reset and clock signals and
-   for setting an initial value for the count register.
-
--  The wishbeone port for reading/writing the count value through the
-   management SoC.
-
-Refer to `user\_project\_wrapper <verilog/rtl/user_project_wrapper.v>`__
-for more information.
-
-.. raw:: html
-
-   <p align="center">
-   <img src="./_static/counter_32.png" width="50%" height="50%">
-   </p>
-
-.. raw:: html
-
-   </p>
-
-Running Full Chip Simulation
-============================
-
-First, you will need to install the simulation environment, by
-
-.. code:: bash
-
-    make simenv
-
-This will pull a docker image with the needed tools installed.
-
-Then, you will need to build the pdk to obtain the verilog views.
-
-.. code:: bash
-
-    # set PDK_ROOT to the path you wish to use for the pdk
-    export PDK_ROOT=<pdk-installation-path>
-
-    # you can optionally specify skywater-pdk and open-pdks commit used
-    # by setting and exporting SKYWATER_COMMIT and OPEN_PDKS_COMMIT
-    # if you do not set them, they default to the last verfied commits tested for this project
-
-    make pdk
-
-Then, run the RTL and GL simulation by
-
-.. code:: bash
-
-    export PDK_ROOT=<pdk-installation-path>
-    export CARAVEL_ROOT=$(pwd)/caravel
-    # specify simulation mode: RTL/GL
-    export SIM=RTL
-    # Run IO ports testbench, make verify-io_ports
-    make verify-<dv-pattern>
-
-The verilog test-benches are under this directory
-`verilog/dv <verilog/dv>`__. For more information on setting up the
-simulation environment and the available testbenches for this sample
-project, refer to `README <verilog/dv/README.md>`__.
-
-Hardening the User Project Macro using Openlane
-===============================================
-
-First, you will need to install the pdk by
-
-.. code:: bash
-
-    # set PDK_ROOT to the path you wish to use for the pdk
-    export PDK_ROOT=<pdk-installation-path>
-
-    # you can optionally specify skywater-pdk and open-pdks commit used
-    # by setting and exporting SKYWATER_COMMIT and OPEN_PDKS_COMMIT
-    # if you do not set them, they default to the last verfied commits tested for this project
-
-    make pdk
-
-Then, you will need to install openlane by
-
-.. code:: bash
-
-    export OPENLANE_ROOT=<openlane-installation-path>
-    export OPENLANE_TAG=v0.12
-    make openlane
-
-For detailed instructions on how to install openlane and the pdk refer
-to
-`README <https://github.com/efabless/openlane/blob/master/README.md>`__.
-
-There are two options for hardening the user project macro using
-openlane:
-
-1. Hardening the user macro, then embedding it in the wrapper
-2. Flattening the user macro with the wrapper.
-
-For more details on this, refer to this
-`README <https://github.com/efabless/caravel/blob/master/openlane/README.rst>`__.
-
-For this sample project, we went for the first option where the user
-macro is hardened first, then it is inserted in the user project
-wrapper.
-
-.. raw:: html
-
-   <p align="center">
-   <img src="./_static/wrapper.png" width="50%" height="50%">
-   </p>
-
-.. raw:: html
-
-   </p>
-
-To reproduce hardening this project, run the following:
-
-.. code:: bash
-
-    export OPENLANE_TAG=v0.12
-    # Run openlane to harden user_proj_example
-    make user_proj_example
-    # Run openlane to harden user_project_wrapper
-    make user_project_wrapper
-
-Checklist for Open-MPW Submission
-=================================
-
--  [x] The project repo adheres to the same directory structure in this
-   repo.
--  [x] The project repo contain info.yaml at the project root.
--  [x] Top level macro is named ``user_project_wrapper``.
--  [x] Full Chip Simulation passes for RTL and GL (gate-level)
--  [x] The hardened Macros are LVS and DRC clean
--  [x] The hardened ``user_project_wrapper`` adheres to the same pin
-   order specified at
-   `pin\_order <https://github.com/efabless/caravel/blob/master/openlane/user_project_wrapper_empty/pin_order.cfg>`__
--  [x] XOR check passes with zero total difference.
--  [x] Openlane summary reports are retained under ./signoff/
-
-.. |License| image:: https://img.shields.io/badge/License-Apache%202.0-blue.svg
-   :target: https://opensource.org/licenses/Apache-2.0
-.. |User CI| image:: https://github.com/efabless/caravel_project_example/actions/workflows/user_project_ci.yml/badge.svg
-   :target: https://github.com/efabless/caravel_project_example/actions/workflows/user_project_ci.yml
-.. |Caravel Build| image:: https://github.com/efabless/caravel_project_example/actions/workflows/caravel_build.yml/badge.svg
-   :target: https://github.com/efabless/caravel_project_example/actions/workflows/caravel_build.yml
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 44e8a31..83f8f0a 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -21,12 +21,13 @@
 Caravel User Project
 ====================
 
-|License| |CI|
+|License| |User CI| |Caravel Build|
 
 Table of contents
 =================
 
 -  `Overview <#overview>`__
+-  `Install Caravel <#install-caravel>`__
 -  `Caravel Integration <#caravel-integration>`__
 
    -  `Repo Integration <#repo-integration>`__
@@ -49,6 +50,40 @@
 repo also demonstrates the recommended structure for the open-mpw
 shuttle projects.
 
+Install Caravel
+===============
+
+To setup caravel, run the following:
+
+.. code:: bash
+
+    # By default, CARAVEL_ROOT is set to $(pwd)/caravel
+    # If you want to install caravel at a different location, run "export CARAVEL_ROOT=<caravel-path>"
+    # Disable submodule installation if needed by, run "export SUBMODULE=0"
+
+    make install
+
+To update the installed caravel to the latest, run:
+
+.. code:: bash
+
+     make update_caravel
+
+To remove caravel, run
+
+.. code:: bash
+
+    make uninstall
+
+By default
+`caravel-lite <https://github.com/efabless/caravel-lite.git>`__ is
+installed. To install the full version of caravel, run this prior to
+calling make install.
+
+.. code:: bash
+
+    export CARAVEL_LITE=0
+
 Caravel Integration
 ===================
 
@@ -56,22 +91,17 @@
 ----------------
 
 Caravel files are kept separate from the user project by having caravel
-as submodule. The submodule commit should point to the latest of caravel
-master. The following files should have a symbolic link to
-`caravel's <https://github.com/efabless/caravel.git>`__ corresponding
-files:
-
--  `Root Makefile <Makefile>`__: This is to make sure that you adhere to
-   the required implementation of the ``compress`` and ``uncompress``
-   targets. Also,
-   `caravel's <https://github.com/efabless/caravel.git>`__ Makefile
-   provides useful targets like running ``lvs``, ``drc``, and ``xor``
-   checks. Run ``make help`` to display the available targets.
+as submodule. The submodule commit should point to the latest of
+caravel/caravel-lite master. The following files should have a symbolic
+link to `caravel's <https://github.com/efabless/caravel.git>`__
+corresponding files:
 
 -  `Openlane Makefile <openlane/Makefile>`__: This provides an easier
-   way for running openlane to harden your macros. Refer to [ Hardening
-   the User Project Macro]. Also, the makefile retains the openlane
-   summary reports under the signoff directory.
+   way for running openlane to harden your macros. Refer to `Hardening
+   the User Project Macro using
+   Openlane <#hardening-the-user-project-macro-using-openlane>`__. Also,
+   the makefile retains the openlane summary reports under the signoff
+   directory.
 
 -  `Pin order <openlane/user_project_wrapper/pin_order.cfg>`__ file for
    the user wrapper: The hardened user project wrapper macro must have
@@ -79,16 +109,7 @@
    the same order will fail the gds integration of the macro with
    caravel's back-end.
 
-To create the symbolic links run the following:
-
-.. code:: bash
-
-    # In case caravel is sub-moduled under the project root, export CARAVEL_ROOT=caravel
-    export CARAVEL_ROOT=<caravel-path> 
-
-    ln -s $CARAVEL_ROOT/Makefile  Makefile
-    ln -s $CARAVEL_ROOT/openlane/Makefile openlane/Makefile
-    ln -s $CARAVEL_ROOT/openlane/user_project_wrapper_empty/pin_order.cfg openlane/user_project_wrapper/pin_order.cfg
+The symbolic links are automatically set when you run ``make install``.
 
 Verilog Integration
 -------------------
@@ -119,7 +140,7 @@
    <p align="center">
    <img src="./_static/counter_32.png" width="50%" height="50%">
    </p>
-   
+
 .. raw:: html
 
    </p>
@@ -127,15 +148,69 @@
 Running Full Chip Simulation
 ============================
 
-The verilog test-benches are under this `verilog/dv <verilog/dv>`__. For
-more information on setting up the simulation environment and the
-available testbenches for this sample project, refer to
-`README <verilog/dv/README.md>`__.
+First, you will need to install the simulation environment, by
+
+.. code:: bash
+
+    make simenv
+
+This will pull a docker image with the needed tools installed.
+
+Then, you will need to build the pdk to obtain the verilog views.
+
+.. code:: bash
+
+    # set PDK_ROOT to the path you wish to use for the pdk
+    export PDK_ROOT=<pdk-installation-path>
+
+    # you can optionally specify skywater-pdk and open-pdks commit used
+    # by setting and exporting SKYWATER_COMMIT and OPEN_PDKS_COMMIT
+    # if you do not set them, they default to the last verfied commits tested for this project
+
+    make pdk
+
+Then, run the RTL and GL simulation by
+
+.. code:: bash
+
+    export PDK_ROOT=<pdk-installation-path>
+    export CARAVEL_ROOT=$(pwd)/caravel
+    # specify simulation mode: RTL/GL
+    export SIM=RTL
+    # Run IO ports testbench, make verify-io_ports
+    make verify-<dv-pattern>
+
+The verilog test-benches are under this directory
+`verilog/dv <verilog/dv>`__. For more information on setting up the
+simulation environment and the available testbenches for this sample
+project, refer to `README <verilog/dv/README.md>`__.
 
 Hardening the User Project Macro using Openlane
 ===============================================
 
-For instructions on how to install openlane and the pdk refer to
+First, you will need to install the pdk by
+
+.. code:: bash
+
+    # set PDK_ROOT to the path you wish to use for the pdk
+    export PDK_ROOT=<pdk-installation-path>
+
+    # you can optionally specify skywater-pdk and open-pdks commit used
+    # by setting and exporting SKYWATER_COMMIT and OPEN_PDKS_COMMIT
+    # if you do not set them, they default to the last verfied commits tested for this project
+
+    make pdk
+
+Then, you will need to install openlane by
+
+.. code:: bash
+
+    export OPENLANE_ROOT=<openlane-installation-path>
+    export OPENLANE_TAG=v0.12
+    make openlane
+
+For detailed instructions on how to install openlane and the pdk refer
+to
 `README <https://github.com/efabless/openlane/blob/master/README.md>`__.
 
 There are two options for hardening the user project macro using
@@ -145,7 +220,7 @@
 2. Flattening the user macro with the wrapper.
 
 For more details on this, refer to this
-`README <caravel/blob/master/openlane/README.rst>`__.
+`README <https://github.com/efabless/caravel/blob/master/openlane/README.rst>`__.
 
 For this sample project, we went for the first option where the user
 macro is hardened first, then it is inserted in the user project
@@ -157,12 +232,15 @@
    <img src="./_static/wrapper.png" width="50%" height="50%">
    </p>
 
+.. raw:: html
+
+   </p>
+
 To reproduce hardening this project, run the following:
 
 .. code:: bash
 
     export OPENLANE_TAG=v0.12
-    cd openlane
     # Run openlane to harden user_proj_example
     make user_proj_example
     # Run openlane to harden user_project_wrapper
@@ -185,5 +263,7 @@
 
 .. |License| image:: https://img.shields.io/badge/License-Apache%202.0-blue.svg
    :target: https://opensource.org/licenses/Apache-2.0
-.. |CI| image:: https://github.com/efabless/caravel_project_example/actions/workflows/caravel_example_ci.yml/badge.svg
-   :target: https://github.com/efabless/caravel_project_example/actions/workflows/caravel_example_ci.yml
+.. |User CI| image:: https://github.com/efabless/caravel_project_example/actions/workflows/user_project_ci.yml/badge.svg
+   :target: https://github.com/efabless/caravel_project_example/actions/workflows/user_project_ci.yml
+.. |Caravel Build| image:: https://github.com/efabless/caravel_project_example/actions/workflows/caravel_build.yml/badge.svg
+   :target: https://github.com/efabless/caravel_project_example/actions/workflows/caravel_build.yml
\ No newline at end of file