Index: .gitignore
===================================================================
--- .gitignore	(revision 946cdc8e3a248b1d6d56a371c9aef64f499bced8)
+++ .gitignore	(revision 61ba6233ec36e842d625c589deec77f689b2a9b6)
@@ -9,3 +9,4 @@
 /doc/api/
 /doc/model/
+/doc/ref/models
 .mplconfig
Index: doc/Makefile
===================================================================
--- doc/Makefile	(revision 19dcb93366741a275baa8ad855ce8a310dca78f8)
+++ doc/Makefile	(revision 61ba6233ec36e842d625c589deec77f689b2a9b6)
@@ -32,12 +32,4 @@
 MODELS_RST = $(patsubst ../sasmodels/models/%.py,model/%.rst,$(MODELS_PY))
 
-model/img/%: ../sasmodels/models/img/%
-	$(COPY) $< $@
-
-model/%.rst: ../sasmodels/models/%.py
-	$(PYTHON) genmodel.py $< $@
-
-.PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest build
-
 help:
 	@echo "Please use \`make <target>' where <target> is one of"
@@ -53,4 +45,15 @@
 	@echo "  doctest   to run all doctests embedded in the documentation (if enabled)"
 
+model/img/%: ../sasmodels/models/img/%
+	$(COPY) $< $@
+
+model/%.rst: ../sasmodels/models/%.py
+	$(PYTHON) genmodel.py $< $@
+
+ref/models/index.rst: gentoc.py $(MODELS_PY)
+	$(PYTHON) gentoc.py $(MODELS_PY)
+
+.PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest build
+
 api: genapi.py
 	$(RMDIR) api
@@ -61,5 +64,5 @@
 	$(MKDIR) model/img
 
-build: model $(MODELS_RST) $(IMG_DEST) api
+build: model $(MODELS_RST) $(IMG_DEST) api ref/models/index.rst
 	#cd ../.. && python setup.py build
 
Index: doc/genmodel.py
===================================================================
--- doc/genmodel.py	(revision cb6ecf4c19ecd47d43632a230eb29c56fba61a7c)
+++ doc/genmodel.py	(revision 61ba6233ec36e842d625c589deec77f689b2a9b6)
@@ -3,5 +3,5 @@
 sys.path.insert(0,'..')
 
-# Convert ../sasmodels/models.name.py to sasmodels.models.name
+# Convert ../sasmodels/models/name.py to sasmodels.models.name
 module_name = sys.argv[1][3:-3].replace('/','.').replace('\\','.')
 print module_name
Index: doc/gentoc.py
===================================================================
--- doc/gentoc.py	(revision 61ba6233ec36e842d625c589deec77f689b2a9b6)
+++ doc/gentoc.py	(revision 61ba6233ec36e842d625c589deec77f689b2a9b6)
@@ -0,0 +1,112 @@
+import sys
+# make sure sasmodels is on the path
+sys.path.append('..')
+
+from os import mkdir
+from os.path import basename, exists, join as joinpath
+from sasmodels.core import load_model_definition
+
+
+TEMPLATE="""\
+..
+    Generated from doc/gentoc.py -- DO NOT EDIT --
+
+.. %(label)s:
+
+%(bar)s
+%(title)s
+%(bar)s
+
+.. toctree::
+
+"""
+
+MODEL_TOC_PATH = "ref/models"
+
+def _make_category(category_name, label, title, parent=None):
+    file = open(joinpath(MODEL_TOC_PATH, category_name+".rst"), "w")
+    file.write(TEMPLATE%{'label':label, 'title':title, 'bar':'*'*len(title)})
+    if parent:
+        _add_subcategory(parent, category_name)
+    return file
+
+def _add_subcategory(file, category_name):
+    file.write("    %s.rst\n"%category_name)
+
+def _add_model(file, model_name):
+    file.write("    ../../model/%s.rst\n"%model_name)
+
+def generate_toc(model_files):
+    if not model_files:
+        print >>sys.stderr, "gentoc needs a list of model files"
+
+    # find all categories
+    category = {}
+    for item in model_files:
+        # assume model is in sasmodels/models/name.py, and ignore the full path
+        model_name = basename(item)[:-3]
+        if model_name.startswith('_'): continue
+        model_definition = load_model_definition(model_name)
+        if not hasattr(model_definition, 'category'):
+            print >>sys.stderr, "Missing category for",item
+        else:
+            category.setdefault(model_definition.category,[]).append(model_name)
+
+    # Check category names
+    for k,v in category.items():
+        if len(v) == 1:
+            print >>sys.stderr, "Category %s contains only %s"%(k,v[0])
+
+    # Generate category files
+    # Assume that top-level groups are:
+    #    shape, shape-independent, structure-factor and custom
+    # Supports a two-level category structure.
+
+    if not exists(MODEL_TOC_PATH): mkdir(MODEL_TOC_PATH)
+    model_toc = _make_category(
+        'index',  'Models', 'Model Functions')
+    shape_toc = _make_category(
+        'shape',  'Shapes', 'Shape Functions', model_toc)
+    free_toc = _make_category(
+        'shape-independent',  'Shape-independent',
+        'Shape-Independent Functions', model_toc)
+    struct_toc = _make_category(
+        'structure-factor',  'Structure-factor', 'Structure Factors', model_toc)
+    custom_toc = _make_category(
+        'custom-models',  'Custom-models', 'Custom Models', model_toc)
+    model_toc.close()
+
+    # remember to top level categories
+    cat_files = {
+        'shape':shape_toc,
+        'shape-independent':free_toc,
+        'structure-factor': struct_toc,
+        'custom': custom_toc,
+        }
+
+    # Process the model lists
+    for k,v in sorted(category.items()):
+        if ':' in k:
+            cat,subcat = k.split(':')
+            cat_file = cat_files[cat]
+            label = "-".join((cat,subcat))
+            filename = label
+            title = subcat.capitalize()+" Functions"
+            sub_toc = _make_category(filename, label, title, cat_file)
+            for model in sorted(v):
+                _add_model(sub_toc, model)
+            sub_toc.close()
+        else:
+            if k not in cat_files:
+                print >>sys.stderr, "Unknown category %s containing"%cat, v
+            else:
+                cat_file = cat_files[k]
+                for model in sorted(v):
+                    _add_model(cat_file, model)
+
+    # Close the top-level category files
+    for f in cat_files.values(): f.close()
+
+
+if __name__ == "__main__":
+    generate_toc(sys.argv[1:])
Index: doc/index.rst
===================================================================
--- doc/index.rst	(revision 19dcb93366741a275baa8ad855ce8a310dca78f8)
+++ doc/index.rst	(revision 61ba6233ec36e842d625c589deec77f689b2a9b6)
@@ -15,5 +15,5 @@
 
    guide/index.rst
-   models/index.rst
+   ref/index.rst
    api/index.rst
 
Index: c/models/cylinders.rst
===================================================================
--- doc/models/cylinders.rst	(revision 19dcb93366741a275baa8ad855ce8a310dca78f8)
+++ 	(revision )
@@ -1,11 +1,0 @@
-.. _models-cylinders:
-
-**************
-Cylinder-based
-**************
-
-.. toctree::
-
-   ../model/cylinder.rst
-   ../model/capped_cylinder.rst
-   ../model/core_shell_cylinder.rst
Index: c/models/ellipsoids.rst
===================================================================
--- doc/models/ellipsoids.rst	(revision 19dcb93366741a275baa8ad855ce8a310dca78f8)
+++ 	(revision )
@@ -1,10 +1,0 @@
-.. _models-ellipsoids:
-
-***************
-Ellipsoid-based
-***************
-
-.. toctree::
-
-   ../model/ellipsoid.rst
-   ../model/triaxial_ellipsoid.rst
Index: c/models/index.rst
===================================================================
--- doc/models/index.rst	(revision 19dcb93366741a275baa8ad855ce8a310dca78f8)
+++ 	(revision )
@@ -1,11 +1,0 @@
-*******************
-SAS Model Reference
-*******************
-
-.. toctree::
-   :numbered: 4
-   :maxdepth: 4
-
-   intro.rst
-   models.rst
-   refs.rst
Index: c/models/intro.rst
===================================================================
--- doc/models/intro.rst	(revision 19dcb93366741a275baa8ad855ce8a310dca78f8)
+++ 	(revision )
@@ -1,49 +1,0 @@
-
-.. _models-intro:
-
-************
-Introduction
-************
-
-Many of our models use the form factor calculations implemented in a c-library provided by the NIST Center for Neutron
-Research and thus some content and figures in this document are originated from or shared with the NIST SANS Igor-based
-analysis package.
-
-This software provides form factors for various particle shapes. After giving a mathematical definition of each model,
-we show the list of parameters available to the user. Validation plots for each model are also presented.
-
-Instructions on how to use SasView itself are available separately.
-
-To easily compare to the scattering intensity measured in experiments, we normalize the form factors by the volume of
-the particle
-
-.. math::
-
-    P(\vec q) = \frac{P_o(\vec q)}{V} = \frac{1}{V} F(\vec q) F^*(\vec q)
-
-with
-
-    F(\vec q) = \int\int\int dV\rho(\vec r) e^{-i\vec q \cdot \vec r}
-
-where $P_0(\vec q)$ is the un-normalized form factor, $\rho(\vec r)$ is the scattering length density at a given
-point in space and the integration is done over the volume $V$ of the scatterer.
-
-For systems without inter-particle interference, the form factors we provide can be related to the scattering intensity
-by the particle volume fraction
-
-.. math::
-
-    I(\vec q) = \Phi P(\vec q)
-
-Our so-called 1D scattering intensity functions provide $P(Q)$ for the case where the scatterer is randomly oriented. In
-that case, the scattering intensity only depends on the length of $Q$ . The intensity measured on the plane of the SAS
-detector will have an azimuthal symmetry around $Q=0$.
-
-Our so-called 2D scattering intensity functions provide $P(Q,\phi)$ for an oriented system as a function of a
-$q$ vector in the plane of the detector. We define the angle $\phi$ as the angle between the $q$ vector and the horizontal
-($x$) axis of the plane of the detector.
-
-For information about polarised and magnetic scattering, see here_.
-
-
-.. _here: polar_mag_help.html
Index: c/models/lamellae.rst
===================================================================
--- doc/models/lamellae.rst	(revision 19dcb93366741a275baa8ad855ce8a310dca78f8)
+++ 	(revision )
@@ -1,9 +1,0 @@
-.. _models-lamellae:
-
-**************
-Lamellae-based
-**************
-
-.. toctree::
-
-   ../model/lamellar.rst
Index: c/models/models.rst
===================================================================
--- doc/models/models.rst	(revision 19dcb93366741a275baa8ad855ce8a310dca78f8)
+++ 	(revision )
@@ -1,14 +1,0 @@
-.. _models:
-
-******
-Models
-******
-
-.. toctree::
-   :numbered:
-   :maxdepth: 4
-
-   shapes.rst
-   independent.rst
-   structures.rst
-   custom.rst
Index: c/models/refs.rst
===================================================================
--- doc/models/refs.rst	(revision 19dcb93366741a275baa8ad855ce8a310dca78f8)
+++ 	(revision )
@@ -1,35 +1,0 @@
-.. _models-refs:
-
-**********
-References
-**********
-
-*Small-Angle Scattering of X-Rays*
-A Guinier and G Fournet
-John Wiley & Sons, New York (1955)
-
-P Stckel, R May, I Strell, Z Cejka, W Hoppe, H Heumann, W Zillig and H Crespi
-*Eur. J. Biochem.*, 112, (1980), 411-417
-
-G Porod
-in *Small Angle X-ray Scattering*
-(editors) O Glatter and O Kratky
-Academic Press (1982)
-
-*Structure Analysis by Small-Angle X-Ray and Neutron Scattering*
-L.A Feigin and D I Svergun
-Plenum Press, New York (1987)
-
-S Hansen
-*J. Appl. Cryst.* 23, (1990), 344-346
-
-S J Henderson
-*Biophys. J.* 70, (1996), 1618-1627
-
-B C McAlister and B P Grady
-*J. Appl. Cryst.* 31, (1998), 594-599
-
-S R Kline
-*J Appl. Cryst.* 39(6), (2006), 895
-
-**Also see the references at the end of the each model function descriptions.**
Index: c/models/shapes.rst
===================================================================
--- doc/models/shapes.rst	(revision 19dcb93366741a275baa8ad855ce8a310dca78f8)
+++ 	(revision )
@@ -1,15 +1,0 @@
-.. _models-shapes:
-
-******************
-Shape-based Models
-******************
-
-.. toctree::
-
-    spheres.rst
-    cylinders.rst
-    ellipsoids.rst
-    lamellae.rst
-    paracrystals.rst
-    parallelpipeds.rst
-
Index: c/models/spheres.rst
===================================================================
--- doc/models/spheres.rst	(revision 19dcb93366741a275baa8ad855ce8a310dca78f8)
+++ 	(revision )
@@ -1,10 +1,0 @@
-.. _models-spheres:
-
-***************
-Sphere-based
-***************
-
-.. toctree::
-
-   ../model/sphere.rst
-
Index: doc/ref/index.rst
===================================================================
--- doc/ref/index.rst	(revision 61ba6233ec36e842d625c589deec77f689b2a9b6)
+++ doc/ref/index.rst	(revision 61ba6233ec36e842d625c589deec77f689b2a9b6)
@@ -0,0 +1,11 @@
+*******************
+SAS Model Reference
+*******************
+
+.. toctree::
+   :numbered: 4
+   :maxdepth: 4
+
+   intro.rst
+   models/index.rst
+   refs.rst
Index: doc/ref/intro.rst
===================================================================
--- doc/ref/intro.rst	(revision 61ba6233ec36e842d625c589deec77f689b2a9b6)
+++ doc/ref/intro.rst	(revision 61ba6233ec36e842d625c589deec77f689b2a9b6)
@@ -0,0 +1,49 @@
+
+.. _models-intro:
+
+************
+Introduction
+************
+
+Many of our models use the form factor calculations implemented in a c-library provided by the NIST Center for Neutron
+Research and thus some content and figures in this document are originated from or shared with the NIST SANS Igor-based
+analysis package.
+
+This software provides form factors for various particle shapes. After giving a mathematical definition of each model,
+we show the list of parameters available to the user. Validation plots for each model are also presented.
+
+Instructions on how to use SasView itself are available separately.
+
+To easily compare to the scattering intensity measured in experiments, we normalize the form factors by the volume of
+the particle
+
+.. math::
+
+    P(\vec q) = \frac{P_o(\vec q)}{V} = \frac{1}{V} F(\vec q) F^*(\vec q)
+
+with
+
+    F(\vec q) = \int\int\int dV\rho(\vec r) e^{-i\vec q \cdot \vec r}
+
+where $P_0(\vec q)$ is the un-normalized form factor, $\rho(\vec r)$ is the scattering length density at a given
+point in space and the integration is done over the volume $V$ of the scatterer.
+
+For systems without inter-particle interference, the form factors we provide can be related to the scattering intensity
+by the particle volume fraction
+
+.. math::
+
+    I(\vec q) = \Phi P(\vec q)
+
+Our so-called 1D scattering intensity functions provide $P(Q)$ for the case where the scatterer is randomly oriented. In
+that case, the scattering intensity only depends on the length of $Q$ . The intensity measured on the plane of the SAS
+detector will have an azimuthal symmetry around $Q=0$.
+
+Our so-called 2D scattering intensity functions provide $P(Q,\phi)$ for an oriented system as a function of a
+$q$ vector in the plane of the detector. We define the angle $\phi$ as the angle between the $q$ vector and the horizontal
+($x$) axis of the plane of the detector.
+
+For information about polarised and magnetic scattering, see here_.
+
+
+.. _here: polar_mag_help.html
Index: doc/ref/refs.rst
===================================================================
--- doc/ref/refs.rst	(revision 61ba6233ec36e842d625c589deec77f689b2a9b6)
+++ doc/ref/refs.rst	(revision 61ba6233ec36e842d625c589deec77f689b2a9b6)
@@ -0,0 +1,35 @@
+.. _models-refs:
+
+**********
+References
+**********
+
+*Small-Angle Scattering of X-Rays*
+A Guinier and G Fournet
+John Wiley & Sons, New York (1955)
+
+P Stckel, R May, I Strell, Z Cejka, W Hoppe, H Heumann, W Zillig and H Crespi
+*Eur. J. Biochem.*, 112, (1980), 411-417
+
+G Porod
+in *Small Angle X-ray Scattering*
+(editors) O Glatter and O Kratky
+Academic Press (1982)
+
+*Structure Analysis by Small-Angle X-Ray and Neutron Scattering*
+L.A Feigin and D I Svergun
+Plenum Press, New York (1987)
+
+S Hansen
+*J. Appl. Cryst.* 23, (1990), 344-346
+
+S J Henderson
+*Biophys. J.* 70, (1996), 1618-1627
+
+B C McAlister and B P Grady
+*J. Appl. Cryst.* 31, (1998), 594-599
+
+S R Kline
+*J Appl. Cryst.* 39(6), (2006), 895
+
+**Also see the references at the end of the each model function descriptions.**
Index: sasmodels/generate.py
===================================================================
--- sasmodels/generate.py	(revision 61371243729a8773396b45547367b0a7771812bc)
+++ sasmodels/generate.py	(revision a5d0d008778409dd90a86aa3db6037187ed3ff57)
@@ -210,4 +210,5 @@
 RST_UNITS = {
     "Ang": "|Ang|",
+    "1/Ang": "|Ang^-1|",
     "1/Ang^2": "|Ang^-2|",
     "1e-6/Ang^2": "|1e-6Ang^-2|",
Index: sasmodels/models/barbell.py
===================================================================
--- sasmodels/models/barbell.py	(revision 0706431576a8920e01fbe34cc6c63d2af1648d77)
+++ sasmodels/models/barbell.py	(revision a5d0d008778409dd90a86aa3db6037187ed3ff57)
@@ -16,5 +16,5 @@
 The barbell geometry is defined as
 
-.. image:: img/image105.jpg
+.. image:: img/barbell_geometry.jpg
 
 where *r* is the radius of the cylinder. All other parameters are as defined in the diagram.
@@ -71,20 +71,9 @@
 **The requirement that** *R* >= *r* **is not enforced in the model!** It is up to you to restrict this during analysis.
 
-This example dataset is produced by running the Macro PlotBarbell(), using 200 data points, *qmin* = 0.001 |Ang^-1|,
-*qmax* = 0.7 |Ang^-1| and the following default values
+This example dataset is produced by running the Macro PlotBarbell(),
+using 200 data points, *qmin* = 0.001 |Ang^-1|, *qmax* = 0.7 |Ang^-1|,
+*sld* = 4e-6 |Ang^-2| and the default model values.
 
-==============  ========  =============
-Parameter name  Units     Default value
-==============  ========  =============
-scale           None      1.0
-len_bar         |Ang|     400.0
-rad_bar         |Ang|     20.0
-rad_bell        |Ang|     40.0
-sld_barbell     |Ang^-2|  1.0e-006
-sld_solv        |Ang^-2|  6.3e-006
-background      |cm^-1|   0
-==============  ========  =============
-
-.. image:: img/image110.jpg
+.. image:: img/barbell_1d.jpg
 
 *Figure. 1D plot using the default values (w/256 data point).*
@@ -93,5 +82,5 @@
 |theta| = 45 deg and |phi| = 0 deg with default values for other parameters
 
-.. image:: img/image111.jpg
+.. image:: img/barbell_2d.jpg
 
 *Figure. 2D plot (w/(256X265) data points).*
@@ -106,4 +95,5 @@
 
 REFERENCE
+---------
 
 H Kaya, *J. Appl. Cryst.*, 37 (2004) 37 223-230
@@ -122,4 +112,5 @@
 		It must be that rad_bar <(=) rad_bell.
 """
+category = "shape:cylinder"
 
 parameters = [
Index: sasmodels/models/bcc.py
===================================================================
--- sasmodels/models/bcc.py	(revision e166cb94a55915b1239c64a45fdab6799a81625f)
+++ sasmodels/models/bcc.py	(revision a5d0d008778409dd90a86aa3db6037187ed3ff57)
@@ -3,7 +3,8 @@
 #note - calculation requires double precision
 """
-Calculates the scattering from a **body-centered cubic lattice** with paracrystalline distortion. Thermal vibrations
-are considered to be negligible, and the size of the paracrystal is infinitely large. Paracrystalline distortion is
-assumed to be isotropic and characterized by a Gaussian distribution.
+Calculates the scattering from a **body-centered cubic lattice** with
+paracrystalline distortion. Thermal vibrations are considered to be negligible,
+and the size of the paracrystal is infinitely large. Paracrystalline distortion
+is assumed to be isotropic and characterized by a Gaussian distribution.
 
 The returned value is scaled to units of |cm^-1|\ |sr^-1|, absolute scale.
@@ -12,62 +13,86 @@
 ----------
 
-The scattering intensity *I(q)* is calculated as
+The scattering intensity $I(q)$ is calculated as
 
-.. image:: img/image167.jpg
+.. math:
 
-where *scale* is the volume fraction of spheres, *Vp* is the volume of the primary particle, *V(lattice)* is a volume
-correction for the crystal structure, *P(q)* is the form factor of the sphere (normalized), and *Z(q)* is the
-paracrystalline structure factor for a body-centered cubic structure.
+    I(q) = \frac{\text{scale}}{V_P} V_\text{lattice} P(q) Z(q)
 
-Equation (1) of the 1990 reference is used to calculate *Z(q)*, using equations (29)-(31) from the 1987 paper for
-*Z1*\ , *Z2*\ , and *Z3*\ .
 
-The lattice correction (the occupied volume of the lattice) for a body-centered cubic structure of particles of radius
-*R* and nearest neighbor separation *D* is
+where *scale* is the volume fraction of spheres, *Vp* is the volume of the
+primary particle, *V(lattice)* is a volume correction for the crystal
+structure, $P(q)$ is the form factor of the sphere (normalized), and $Z(q)$
+is the paracrystalline structure factor for a body-centered cubic structure.
 
-.. image:: img/image159.jpg
+Equation (1) of the 1990 reference is used to calculate $Z(q)$, using
+equations (29)-(31) from the 1987 paper for *Z1*\ , *Z2*\ , and *Z3*\ .
 
-The distortion factor (one standard deviation) of the paracrystal is included in the calculation of *Z(q)*
+The lattice correction (the occupied volume of the lattice) for a
+body-centered cubic structure of particles of radius $R$ and nearest neighbor
+separation $D$ is
 
-.. image:: img/image160.jpg
+.. math:
 
-where *g* is a fractional distortion based on the nearest neighbor distance.
+    V_\text{lattice} = \frac{16\pi}{3} \frac{R^3}{\left(D\sqrt{2}\right)^3}
+
+
+The distortion factor (one standard deviation) of the paracrystal is included
+in the calculation of $Z(q)$
+
+.. math:
+
+    \Delta a = g D
+
+where $g$ is a fractional distortion based on the nearest neighbor distance.
 
 The body-centered cubic lattice is
 
-.. image:: img/image168.jpg
+.. image:: img/bcc_lattice.jpg
 
 For a crystal, diffraction peaks appear at reduced q-values given by
 
-.. image:: img/image162.jpg
+.. math:
 
-where for a body-centered cubic lattice, only reflections where (\ *h* + *k* + *l*\ ) = even are allowed and
-reflections where (\ *h* + *k* + *l*\ ) = odd are forbidden. Thus the peak positions correspond to (just the first 5)
+    \frac{qD}{2\pi} = \sqrt{h^2 + k^2 + l^2}
 
-.. image:: img/image169.jpg
+where for a body-centered cubic lattice, only reflections where
+$(h + k + l) = \text{even}$ are allowed and reflections where
+$(h + k + l) = \text{odd}$ are forbidden. Thus the peak positions
+correspond to (just the first 5)
 
-**NB: The calculation of** *Z(q)* **is a double numerical integral that must be carried out with a high density of**
-**points to properly capture the sharp peaks of the paracrystalline scattering.** So be warned that the calculation is
-SLOW. Go get some coffee. Fitting of any experimental data must be resolution smeared for any meaningful fit. This
-makes a triple integral. Very, very slow. Go get lunch!
+.. math:
 
-This example dataset is produced using 200 data points, *qmin* = 0.001 |Ang^-1|, *qmax* = 0.1 |Ang^-1| and the above
-default values.
+    \begin{eqnarray}
+    &q/q_o&&\quad 1&& \ \sqrt{2} && \ \sqrt{3} && \ \sqrt{4} && \ \sqrt{5} \\
+    &\text{Indices}&& (110) && (200) && (211) && (220) && (310)
+    \end{eqnarray}
 
-.. image:: img/image170.jpg
+**NB: The calculation of $Z(q)$ is a double numerical integral that must
+be carried out with a high density of points to properly capture the sharp
+peaks of the paracrystalline scattering.** So be warned that the calculation
+is SLOW. Go get some coffee. Fitting of any experimental data must be
+resolution smeared for any meaningful fit. This makes a triple integral.
+Very, very slow. Go get lunch!
+
+This example dataset is produced using 200 data points,
+*qmin* = 0.001 |Ang^-1|, *qmax* = 0.1 |Ang^-1| and the above default values.
+
+.. image:: img/bcc_1d.jpg
 
 *Figure. 1D plot in the linear scale using the default values (w/200 data point).*
 
-The 2D (Anisotropic model) is based on the reference below where *I(q)* is approximated for 1d scattering. Thus the
-scattering pattern for 2D may not be accurate. Note that we are not responsible for any incorrectness of the 2D model
-computation.
+The 2D (Anisotropic model) is based on the reference below where $I(q)$ is
+approximated for 1d scattering. Thus the scattering pattern for 2D may not
+be accurate. Note that we are not responsible for any incorrectness of the 2D
+model computation.
 
-.. image:: img/image165.gif
+.. image:: img/bcc_orientation.gif
 
-.. image:: img/image171.jpg
+.. image:: img/bcc_2d.jpg
 
 *Figure. 2D plot using the default values (w/200X200 pixels).*
 
 REFERENCE
+---------
 
 Hideki Matsuoka et. al. *Physical Review B*, 36 (1987) 1754-1765
@@ -87,4 +112,5 @@
     assumed to be isotropic and characterized by a Gaussian distribution.
     """
+category="shape:paracrystal"
 
 parameters = [
Index: sasmodels/models/broad_peak.py
===================================================================
--- sasmodels/models/broad_peak.py	(revision f734e7d992ea6f2199f478553447ff0dbe047559)
+++ sasmodels/models/broad_peak.py	(revision a5d0d008778409dd90a86aa3db6037187ed3ff57)
@@ -30,15 +30,4 @@
     q = \sqrt{q_x^2 + q_y^2}
 
-=====================  =========  =============
-Parameter name          Units     Default value
-=====================  =========  =============
-lorentz_scale(=C)       None      10
-porod_scale  (=A)       None      1e-05
-lorentz_length (= |xi| )  |Ang|     50
-peak_pos  (=Q0)         |Ang^-1|  0.1
-porod_exp  (=n)         None      2
-lorentz_exp (=m)        None      3
-Background (=B)        |cm^-1|   0.1
-==================  ========  =============
 
 .. image:: img/image175.jpg
@@ -47,4 +36,5 @@
 
 REFERENCE
+---------
 
 None.
@@ -71,4 +61,5 @@
       lorentz_exp = Lorentzian exponent
       background = Incoherent background"""
+category="shape-independent"
 
 parameters = [
Index: sasmodels/models/capped_cylinder.py
===================================================================
--- sasmodels/models/capped_cylinder.py	(revision a503bfddd742ec35fe2b801f1d75a0a5f11eccfa)
+++ sasmodels/models/capped_cylinder.py	(revision a5d0d008778409dd90a86aa3db6037187ed3ff57)
@@ -130,4 +130,5 @@
 	solvent_sld: SLD of the solvent.
 """
+category = "shape:cylinder"
 
 parameters = [
Index: sasmodels/models/core_shell_cylinder.py
===================================================================
--- sasmodels/models/core_shell_cylinder.py	(revision a503bfddd742ec35fe2b801f1d75a0a5f11eccfa)
+++ sasmodels/models/core_shell_cylinder.py	(revision a5d0d008778409dd90a86aa3db6037187ed3ff57)
@@ -133,4 +133,5 @@
  	phi: the axis_phi of the cylinder
 """
+category = "shape:cylinder"
 
 parameters = [
Index: sasmodels/models/cylinder.py
===================================================================
--- sasmodels/models/cylinder.py	(revision 43bdddcd8c2b2ad9795e6bc69c43314fc3a617fd)
+++ sasmodels/models/cylinder.py	(revision a5d0d008778409dd90a86aa3db6037187ed3ff57)
@@ -128,4 +128,5 @@
             f(q,alpha)^(2)*sin(alpha)*dalpha + background
 """
+category = "shape:cylinder"
 
 parameters = [
Index: sasmodels/models/dab.py
===================================================================
--- sasmodels/models/dab.py	(revision 80768fc3cd0178067d0f776b9188107e2c66a74a)
+++ sasmodels/models/dab.py	(revision a5d0d008778409dd90a86aa3db6037187ed3ff57)
@@ -44,4 +44,5 @@
 
 """
+category = "shape-independent"
 
 parameters = [
Index: sasmodels/models/ellipsoid.py
===================================================================
--- sasmodels/models/ellipsoid.py	(revision a503bfddd742ec35fe2b801f1d75a0a5f11eccfa)
+++ sasmodels/models/ellipsoid.py	(revision a5d0d008778409dd90a86aa3db6037187ed3ff57)
@@ -136,4 +136,5 @@
 		Re: equatorial radius of the ellipsoid
 """
+category = "shape:ellipsoid"
 
 parameters = [
Index: sasmodels/models/fcc.py
===================================================================
--- sasmodels/models/fcc.py	(revision e7b3d7b015b4e57d299b8d962e6f11825c0bad69)
+++ sasmodels/models/fcc.py	(revision a5d0d008778409dd90a86aa3db6037187ed3ff57)
@@ -87,4 +87,5 @@
     assumed to be isotropic and characterized by a Gaussian distribution.
     """
+category = "shape:paracrystal"
 
 parameters = [
Index: sasmodels/models/gaussian_peak.py
===================================================================
--- sasmodels/models/gaussian_peak.py	(revision 6ea6902bb36d43293698f2ce20f8aa36ebde927c)
+++ sasmodels/models/gaussian_peak.py	(revision a5d0d008778409dd90a86aa3db6037187ed3ff57)
@@ -16,4 +16,5 @@
 
 REFERENCE
+---------
 
 None.
@@ -28,11 +29,12 @@
     Provide F(q) = scale*exp( -1/2 *[(q-q0)/B]^2 )+ background
 """
+category = "shape-independent"
 
 parameters = [
 #   [ "name", "units", default, [lower, upper], "type",
 #     "description" ],
-    [ "q0", "Ang^-1", 0.05, [-inf,inf], "",
+    [ "q0", "1/Ang", 0.05, [-inf,inf], "",
       "Peak position" ],
-    [ "sigma", "Ang^-1", 0.005, [-inf,inf], "",
+    [ "sigma", "1/Ang", 0.005, [-inf,inf], "",
       "Peak width (standard deviation)" ],
     ]
Index: sasmodels/models/hardsphere.py
===================================================================
--- sasmodels/models/hardsphere.py	(revision 301e09699a18f9efe29522bd73400f85dc156d6b)
+++ sasmodels/models/hardsphere.py	(revision a5d0d008778409dd90a86aa3db6037187ed3ff57)
@@ -1,9 +1,16 @@
 # Note: model title and parameter table are inserted automatically
-r"""This calculates the interparticle structure factor for monodisperse spherical particles interacting through hard
-sphere (excluded volume) interactions.
+r"""Calculate the interparticle structure factor for monodisperse
+spherical particles interacting through hard sphere (excluded volume)
+interactions.
 
-The calculation uses the Percus-Yevick closure where the interparticle potential is
+The calculation uses the Percus-Yevick closure where the interparticle
+potential is
 
-.. image:: img/HardSphere_223.PNG
+.. math:
+
+    U(r) = \begin{cases}
+    \infty & r < 2R \\
+    0 & r \geq 2R
+    \end{cases}
 
 where *r* is the distance from the center of the sphere of a radius *R*.
@@ -13,15 +20,8 @@
 .. math::
 
-    Q = \sqrt{Q_x^2 + Q_y^2}
+    q = \sqrt{q_x^2 + q_y^2}
 
 
-==============  ========  =============
-Parameter name  Units     Default value
-==============  ========  =============
-effect_radius   |Ang|     50.0
-volfraction     None      0.2
-==============  ========  =============
-
-.. image:: img/HardSphere_224.jpg
+.. image:: img/HardSphere_1d.jpg
 
 *Figure. 1D plot using the default values (in linear scale).*
@@ -39,11 +39,12 @@
 	[Hard sphere structure factor, with Percus-Yevick closure]
         Interparticle S(Q) for random, non-interacting spheres.
-		May be a reasonable approximation for other shapes of
-		particles that freely rotate, and for moderately polydisperse
+	May be a reasonable approximation for other shapes of
+	particles that freely rotate, and for moderately polydisperse
         systems. Though strictly the maths needs to be modified - 
-		which sasview does not do yet.
-		effect_radius is the hard sphere radius
-		volfraction is the volume fraction occupied by the spheres.
+	which sasview does not do yet.
+	effect_radius is the hard sphere radius
+	volfraction is the volume fraction occupied by the spheres.
 """
+category = "structure-factor"
 
 parameters = [
@@ -96,5 +97,5 @@
 Iqxy = """
     // never called since no orientation or magnetic parameters.
-    return -1.0;
+    return Iq(sqrt(qx*qx+qy*qy), IQ_PARAMETERS);
     """
 
Index: sasmodels/models/lamellar.py
===================================================================
--- sasmodels/models/lamellar.py	(revision a503bfddd742ec35fe2b801f1d75a0a5f11eccfa)
+++ sasmodels/models/lamellar.py	(revision a5d0d008778409dd90a86aa3db6037187ed3ff57)
@@ -61,4 +61,5 @@
 		scale = scale factor
 """
+category = "shape:lamellae"
 
 parameters = [
Index: sasmodels/models/lamellarCaille.py
===================================================================
--- sasmodels/models/lamellarCaille.py	(revision dc02af0f5a8fa1ee637e4aeeee5e5fe5c977ce74)
+++ sasmodels/models/lamellarCaille.py	(revision a5d0d008778409dd90a86aa3db6037187ed3ff57)
@@ -1,60 +1,68 @@
 # Note: model title and parameter table are inserted automatically
 r"""
-This model provides the scattering intensity, *I(q)* = *P(q)* \* *S(q)*, for a lamellar phase where a random
-distribution in solution are assumed. Here a Caille S(Q) is used for the lamellar stacks.
+This model provides the scattering intensity, $I(q) = P(q) S(q)$, for a
+lamellar phase where a random distribution in solution are assumed.
+Here a Caille $S(Q)$ is used for the lamellar stacks.
 
-The scattering intensity *I(q)* is
+The scattering intensity $I(q)$ is
 
-.. image:: img/lamellarCaille_139.PNG
+.. math:
+
+    I(q) = 2\pi \frac{P(q)S(q)}{\delta q^2}
 
 The form factor is
 
-.. image:: img/lamellarCaille_134.PNG
+.. math:
+
+    P(q) = \frac{2\Delta\rho^2}{q^2}\left(1-\cos q\delta \right)
 
 and the structure factor is
 
-.. image:: img/lamellarCaille_.PNG
+.. math:
+
+    S(q) = 1 + 2 \sum_1^{N-1}\left(1-\frac{n}{N}\right)
+           \cos(qdn)\exp\left(-\frac{2q^2d^2\alpha(n)}{2}\right)
 
 where
 
-.. image:: img/lamellarCaille_.PNG
+.. math:
 
-Here *d* = (repeat) spacing, |delta| = bilayer thickness, the contrast |drho| = SLD(headgroup) - SLD(solvent),
-K = smectic bending elasticity, B = compression modulus, and N = number of lamellar plates (*n_plates*).
+    \begin{eqnarray}
+    \alpha(n) &=& \frac{\eta_{cp}}{4\pi^2} \left(\ln(\pi n)+\gamma_E\right)  \\
+    \gamma_E &=& 0.5772156649 && \text{Euler's constant} \\
+    \eta_{cp} &=& \frac{q_o^2k_B T}{8\pi\sqrt{K\overline{B}}} && \text{Caille constant}
+    \end{eqnarray}
 
-NB: **When the Caille parameter is greater than approximately 0.8 to 1.0, the assumptions of the model are incorrect.**
-And due to a complication of the model function, users are responsible for making sure that all the assumptions are
-handled accurately (see the original reference below for more details).
+Here $d$ = (repeat) spacing, $\delta$ = bilayer thickness,
+the contrast $\Delta\rho$ = SLD(headgroup) - SLD(solvent),
+$K$ = smectic bending elasticity, $B$ = compression modulus, and
+$N$ = number of lamellar plates (*n_plates*).
 
-Non-integer numbers of stacks are calculated as a linear combination of results for the next lower and higher values.
+NB: **When the Caille parameter is greater than approximately 0.8 to 1.0, the
+assumptions of the model are incorrect.** And due to a complication of the
+model function, users are responsible for making sure that all the assumptions
+are handled accurately (see the original reference below for more details).
 
-The 2D scattering intensity is calculated in the same way as 1D, where the *q* vector is defined as
+Non-integer numbers of stacks are calculated as a linear combination of
+results for the next lower and higher values.
+
+The 2D scattering intensity is calculated in the same way as 1D, where the
+$q$ vector is defined as
 
 .. math::
 
-    Q = \sqrt{Q_x^2 + Q_y^2}
+    q = \sqrt{q_x^2 + q_y^2}
 
 The returned value is in units of |cm^-1|, on absolute scale.
 
-==============  ========  =============
-Parameter name  Units     Default value
-==============  ========  =============
-background      |cm^-1|   0.0
-contrast        |Ang^-2|  5e-06
-scale           None      1
-delta           |Ang|     30
-n_plates        None      20
-spacing         |Ang|     400
-caille          |Ang^-2|  0.1
-==============  ========  =============
-
-.. image:: img/lamellarPS_142.jpg
+.. image:: img/lamellarCaille_1d.jpg
 
 *Figure. 1D plot using the default values (w/6000 data point).*
 
-Our model uses the form factor calculations implemented in a c-library provided by the NIST Center for Neutron Research
-(Kline, 2006).
+Our model uses the form factor calculations as implemented in a c library
+provided by the NIST Center for Neutron Research (Kline, 2006).
 
 REFERENCE
+---------
 
 F Nallet, R Laversanne, and D Roux, J. Phys. II France, 3, (1993) 487-502
@@ -75,4 +83,5 @@
 		scale = scale factor
 """
+category = "shape:lamellae"
 
 parameters = [
@@ -85,5 +94,5 @@
     [ "spacing", "Ang", 400., [0.0,inf], "volume",
       "d-spacing of Caille S(Q)" ],
-    [ "Caille_parameter", "Ang^-2", 0.1, [0.0,0.8], "",
+    [ "Caille_parameter", "1/Ang^2", 0.1, [0.0,0.8], "",
       "Caille parameter" ],
     [ "sld", "1e-6/Ang^2", 6.3, [-inf,inf], "",
Index: sasmodels/models/lamellarCailleHG.py
===================================================================
--- sasmodels/models/lamellarCailleHG.py	(revision cd55ac368c9896e596edd5249ff69ee16affeb23)
+++ sasmodels/models/lamellarCailleHG.py	(revision a5d0d008778409dd90a86aa3db6037187ed3ff57)
@@ -82,4 +82,5 @@
 		scale = scale factor
 """
+category = "shape:lamellae"
 
 parameters = [
Index: sasmodels/models/lamellarFFHG.py
===================================================================
--- sasmodels/models/lamellarFFHG.py	(revision dc02af0f5a8fa1ee637e4aeeee5e5fe5c977ce74)
+++ sasmodels/models/lamellarFFHG.py	(revision a5d0d008778409dd90a86aa3db6037187ed3ff57)
@@ -71,4 +71,5 @@
 		scale = scale factor
 """
+category = "shape:lamellae"
 
 parameters = [
Index: sasmodels/models/lamellarPC.py
===================================================================
--- sasmodels/models/lamellarPC.py	(revision f734e7d992ea6f2199f478553447ff0dbe047559)
+++ sasmodels/models/lamellarPC.py	(revision a5d0d008778409dd90a86aa3db6037187ed3ff57)
@@ -71,4 +71,5 @@
 		scale = scale factor
 """
+category = "shape:lamellae"
 
 parameters = [
Index: sasmodels/models/parallelepiped.py
===================================================================
--- sasmodels/models/parallelepiped.py	(revision c5b7d07435739547137368520d072f6e87ac3208)
+++ sasmodels/models/parallelepiped.py	(revision a5d0d008778409dd90a86aa3db6037187ed3ff57)
@@ -114,9 +114,10 @@
 	    mu = q*B
 """
+category = "shape:parallelpiped"
 
 parameters = [
 #   [ "name", "units", default, [lower, upper], "type",
 #     "description" ],
-    [ "sld", "6e-6/Ang^2", 4, [-inf,inf], "",
+    [ "sld", "1e-6/Ang^2", 4, [-inf,inf], "",
       "Parallelepiped scattering length density" ],
     [ "solvent_sld", "1e-6/Ang^2", 1, [-inf,inf], "",
Index: sasmodels/models/sphere.py
===================================================================
--- sasmodels/models/sphere.py	(revision a503bfddd742ec35fe2b801f1d75a0a5f11eccfa)
+++ sasmodels/models/sphere.py	(revision a5d0d008778409dd90a86aa3db6037187ed3ff57)
@@ -70,4 +70,5 @@
     solvent_sld: the SLD of the solvent
 """
+category = "shape:sphere"
 
 parameters = [
Index: sasmodels/models/spherepy.py
===================================================================
--- sasmodels/models/spherepy.py	(revision a503bfddd742ec35fe2b801f1d75a0a5f11eccfa)
+++ sasmodels/models/spherepy.py	(revision a5d0d008778409dd90a86aa3db6037187ed3ff57)
@@ -71,4 +71,5 @@
     solvent_sld: the SLD of the solvent
 """
+category = "shape:sphere"
 
 parameters = [
Index: sasmodels/models/stickyhardsphere.py
===================================================================
--- sasmodels/models/stickyhardsphere.py	(revision 9cb1415f91435d97425766c6decbef4cceffec86)
+++ sasmodels/models/stickyhardsphere.py	(revision a5d0d008778409dd90a86aa3db6037187ed3ff57)
@@ -70,4 +70,5 @@
 		parameters used in P(Q).
 """
+category = "structure-factor"
 
 parameters = [
Index: sasmodels/models/triaxial_ellipsoid.py
===================================================================
--- sasmodels/models/triaxial_ellipsoid.py	(revision a503bfddd742ec35fe2b801f1d75a0a5f11eccfa)
+++ sasmodels/models/triaxial_ellipsoid.py	(revision a5d0d008778409dd90a86aa3db6037187ed3ff57)
@@ -100,4 +100,5 @@
 	not be correct.
 """
+category = "shape:ellipsoid"
 
 parameters = [
