Cleaned things up in the build document, added an intro page to direc…

…t you

docs/source/building.rst

@@ -24,38 +24,71 @@ Simple Installation
 ===================
 
 1. Clone the repo and submodules and enter the directory
-   ``$ git clone --recurse-submodules https://github.com/rticommunity/connextdds-py.git``
-   ``$ cd connextdds-py``
+
+.. code-block:: shell
+
+    $ git clone --recurse-submodules https://github.com/rticommunity/connextdds-py.git
+    $ cd connextdds-py
+
 2. Set the environment variables
-   ``$ export NDDSHOME=<install location of Connext Pro>``
-   ``$ export CONNEXTDDS_ARCH=<target arch>``
-   ``$ export LD_LIBRARY_PATH=<location of target libs>:$LD_LIBRARY_PATH``
-   ``$ export NJOBS=<number of concurrent make jobs, default 1>``
+
+.. code-block:: shell
+
+    $ export NDDSHOME=<install location of Connext Pro>
+    $ export CONNEXTDDS_ARCH=<target arch>
+    $ export LD_LIBRARY_PATH=<location of target libs>:$LD_LIBRARY_PATH
+    $ export NJOBS=<number of concurrent make jobs, default 1>
+
 3. Build and install
-   ``$ pip install .``
+
+.. code-block:: shell
+
+    $ pip install .
 
 Development Installation
 ========================
 If you want to cahce the build files, you can use wheels.
 
 1. Install the wheel package using pip.
-   ``$ pip install wheel``
+
+.. code-block:: shell
+
+    $ pip install wheel
+
 2. Clone the repo and submodules and enter the directory
-   ``$ git clone --recurse-submodules https://github.com/rticommunity/connextdds-py.git``
-   ``$ cd connextdds-py``
+
+.. code-block:: shell
+
+    $ git clone --recurse-submodules https://github.com/rticommunity/connextdds-py.git
+    $ cd connextdds-py
+
 3. Set the environment variables
-   ``$ export NDDSHOME=<install location of Connext Pro>``
-   ``$ export CONNEXTDDS_ARCH=<target arch>``
-   ``$ export LD_LIBRARY_PATH=<location of target libs>:$LD_LIBRARY_PATH``
-   ``$ export NJOBS=<number of concurrent make jobs, default 1>``
+
+.. code-block:: shell
+
+    $ export NDDSHOME=<install location of Connext Pro>
+    $ export CONNEXTDDS_ARCH=<target arch>
+    $ export LD_LIBRARY_PATH=<location of target libs>:$LD_LIBRARY_PATH
+    $ export NJOBS=<number of concurrent make jobs, default 1>
+
 4. Run the setup script
-   ``$ python setup.py bdist_wheel``
+
+.. code-block:: shell 
+
+    $ python setup.py bdist_wheel
+
 5. Install the package
-   ``$ pip install dist/*``
+
+.. code-block:: shell
+
+    $ pip install dist/*
 
 
 Uninstalling
 ============
 If you wish to install a new version or update the development version,
 you must uninstall the python package. To do so, run
-``$ pip uninstall rti -y``
+
+.. code-block:: shell
+
+    $ pip uninstall rti -y

docs/source/index.rst

@@ -3,15 +3,20 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
+Welcome!
+========
+
 Welcome to connextdds-py's documentation!
-=========================================
+If you are new, you might want to check out the
+:ref:`intro:Introduction` section!
 
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
 
    quick.rst
    rti.rst
+   intro.rst
    building.rst
    participant.rst
    types.rst

docs/source/intro.rst

@@ -0,0 +1,27 @@
+.. py:currentmodule:: rti.connextdds
+
+Introduction
+~~~~~~~~~~~~
+
+Welcome to connextdds-py! This is the Python API for RTI's ConnextDDS. 
+It is based on the Modern C++ API and is similar but has a few key 
+differences. Due to the dynamic nature of Python, Dynamic Data is 
+the way to define data types. This can be done in IDL files that
+can be converted to XML files, or in code.
+
+The API is almost identical to the Modern C++ API but we follow 
+Python conventions. For example, instead of getters and setters, we 
+utilize properties. If there's a property that is write only,
+it is assigned typically with a call to set_name_of_property.
+
+**Note: It is highly recommmended that you have some experience with
+at least one full ConnextDDS version**
+
+It is recommended that you read the following documentation to 
+understand the Python library.
+
+- :ref:`participant:Participant`
+- :ref:`types:Types`
+- :ref:`topic:Topic`
+- :ref:`writer:Writer`
+- :ref:`reader:Reader`