added index.rst
diff --git a/docs/source/index.rst b/docs/source/index.rst
new file mode 100644
index 0000000..44e8a31
--- /dev/null
+++ b/docs/source/index.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">
+ <img src="./_static/counter_32.png" width="50%" height="50%">
+ </p>
+
+.. 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">
+ <img src="./_static/wrapper.png" width="50%" height="50%">
+ </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
