include more images

README.rst

@@ -46,11 +46,23 @@ theory is used, following `the procedure described by Wiscombe
 <http://opensky.ucar.edu/islandora/object/technotes:232>`_. This code has
 been validated against his results. 
 
-
 .. image:: https://raw.githubusercontent.com/scottprahl/miepython/master/docs/mie-diagram1.png
    :scale: 50 %
    :alt: montage of laser images
 
+This code provides functions for calculating the extinction efficiency,
+scattering efficiency, backscattering, and scattering asymmetry.
+Moreover, a set of angles can be given to calculate the scattering at various
+angles for a sphere.
+
+When comparing different Mie scattering codes, make sure that you're
+aware of the conventions used by each code.  ``miepython`` makes the
+following assumptions
+
+* the imaginary part of the complex index of refraction for absorbing spheres is *negative*.
+
+* the scattering phase function is normalized so it equals the *single scattering albedo* when integrated over 4π steradians by default.  This normalization can be changed As of version 2.3, this can be changed (see the normalization notebook for details).
+
 .. image:: https://raw.githubusercontent.com/scottprahl/miepython/master/docs/mie-diagram2.png
    :scale: 40 %
    :alt: montage of laser images
@@ -83,16 +95,17 @@ or ``conda``::
 
 Or `run this code in the cloud using Google Collaboratory <https://colab.research.google.com/github/scottprahl/miepython/blob/master>`_ by selecting the Jupyter notebook that interests you.
 
-An example
-----------
+Usage for those that don't do Jupyter
+--------------------------------------
 
-The following code::
+Basic Mie Calculations
+^^^^^^^^^^^^^^^^^^^^^^^
 
-    import miepython
+    from miepython import mie
 
-    m = 1.5-1j
-    x = 1
-    qext, qsca, qback, g = miepython.mie(m,x)
+    complex_refractive_index = 1.5-1j    # convention is negative imaginary part
+    size_parameter = 1                   # 2𝜋(radius)/λ
+    qext, qsca, qback, g = mie(complex_refractive_index, size_parameter)
 
     print("The extinction efficiency  is %.3f" % qext)
     print("The scattering efficiency  is %.3f" % qsca)
@@ -106,15 +119,52 @@ should produce::
     The backscatter efficiency is 0.573
     The scattering anisotropy  is 0.192
 
-There are a few short scripts in the github repository.
 
-* `Extinction Efficiency of Absorbing and Non-Absorbing Spheres <https://github.com/scottprahl/miepython/blob/master/miepython/examples/01_dielectric.py>`_
-
-* `Four Micron Glass Spheres <https://github.com/scottprahl/miepython/blob/master/miepython/examples/02_glass.py>`_ 
+Simple Dielectric
+^^^^^^^^^^^^^^^^^^
+
+The script `01_dielectric.py <https://raw.githubusercontent.com/scottprahl/miepython/master/miepython/examples/01_dielectric.py>`_
+
+.. image:: https://raw.githubusercontent.com/scottprahl/miepython/master/docs/01_plot.svg
+
+Glass Spheres
+^^^^^^^^^^^^^^
+
+The script `02_glass.py <https://raw.githubusercontent.com/scottprahl/miepython/master/miepython/examples/02_glass.py>`_
+
+.. image:: https://raw.githubusercontent.com/scottprahl/miepython/master/docs/02_plot.svg
+
+Water Droplets
+^^^^^^^^^^^^^^^
+
+The script `03_droplets.py <https://raw.githubusercontent.com/scottprahl/miepython/master/miepython/examples/03_droplets.py>`_
+
+.. image:: https://raw.githubusercontent.com/scottprahl/miepython/master/docs/03_plot.svg
+
+Small Gold Spheres
+^^^^^^^^^^^^^^^^^^^
+
+The script `04_gold.py <https://raw.githubusercontent.com/scottprahl/miepython/master/miepython/examples/04_gold.py>`_
+
+.. image:: https://raw.githubusercontent.com/scottprahl/miepython/master/docs/04_plot.svg
+
+
+Usage for those that use Jupyter
+---------------------------------
+
+All the Jupyter notebooks are available in the docs directory and they are all viewable at <https://miepython.readthedocs.io>
+
+
+Script Examples for those that don't do Jupyter
+-----------------------------------------------
+
+All the Jupyter notebooks are in the docs directory and shown at <https://miepython.readthedocs.io>
 
-* `One Micron Water Droplets <https://github.com/scottprahl/miepython/blob/master/miepython/examples/03_droplets.py>`_ 
+You can also use a Jupyter notebook immediately (well, you do have wait a bit for everything to get uploaded) by clicking the Google Colaboratory button below
 
-* `Gold Nanospheres <https://github.com/scottprahl/miepython/blob/master/miepython/examples/04_gold.py>`_ 
+.. image:: https://colab.research.google.com/assets/colab-badge.svg
+  :target: https://colab.research.google.com/github/scottprahl/miepython/blob/master
+  :alt: Colab
 
 
 License