diff --git a/docs/source/README.rst b/docs/source/README.rst
new file mode 100644
index 0000000..3d62b77
--- /dev/null
+++ b/docs/source/README.rst
@@ -0,0 +1,189 @@
+.. 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| |CI|
+
+Table of contents
+=================
+
+-  `Overview <#overview>`__
+-  `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.
+
+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
+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.
+
+-  `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.
+
+-  `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.
+
+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
+
+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”>
+
+.. raw:: html
+
+   </p>
+
+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>`__.
+
+Hardening the User Project Macro using Openlane
+===============================================
+
+For 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 <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”>
+
+.. 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
+    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
+.. |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
diff --git a/doc/counter_32.png b/docs/source/_static/counter_32.png
similarity index 100%
rename from doc/counter_32.png
rename to docs/source/_static/counter_32.png
Binary files differ
diff --git a/doc/wrapper.png b/docs/source/_static/wrapper.png
similarity index 100%
rename from doc/wrapper.png
rename to docs/source/_static/wrapper.png
Binary files differ