Update documentation

docs/conf.py

@@ -1,5 +1,7 @@
 # Configuration file for the Sphinx documentation builder.
 
+import sphinx_rtd_theme
+
 # -- Project information
 
 project = 'OpenCMISS ZincWidgets'
@@ -29,7 +31,8 @@
 
 # -- Options for HTML output
 
-html_theme = 'nature'
+html_theme = "sphinx_rtd_theme"
+html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 
 # -- Options for EPUB output
 epub_show_urls = 'footnote'

docs/fieldeditorwidget.rst

@@ -1,3 +1,6 @@
+.. _Field-Editor-Widget:
+
+===================
 Field Editor Widget
 ===================
 
@@ -7,6 +10,7 @@ The **Field Editor Widget** is a control to add, remove, and modify fields in a
 
 .. figure:: _images/field-editor-widget.png
    :alt: Field editor widget.
+   :width: 75%
 
    Field editor widget.
 
@@ -33,8 +37,3 @@ It contains a number of controls.
 * Source field: This drop-down menu allows you to select an existing field as a source field for a new field, only enabled when creating a new field.
 * Component indexes: This text box shows and allows you to change the component indexes of the selected field.
 
-API
----
-
-.. autoclass:: opencmiss.zincwidgets.fieldeditorwidget.FieldEditorWidget
-   :members:

docs/graphicseditorwidget.rst

@@ -1,50 +1,105 @@
+.. _Graphics-Editor-Widget:
+
+======================
 Graphics Editor Widget
 ======================
 
-The **Graphics Editor Widget** is a control to add, remove, and modify the graphics of a scene.
+The **Graphics Editor Widget** is where each graphical setting can be edited. 
+When a graphical setting is selected from the list, all of its editable properties appear in this area. 
+The range of editable properties will vary depending on the type of graphics currently selected.
 
 .. _fig-opencmiss-zincwidgets-graphics-editor-widget:
 
 .. figure:: _images/graphics-editor-widget.png
    :alt: Graphics editor widget.
+   :width: 75%
 
    Graphics editor widget.
 
-Settings editor
----------------
+This widget usually been used with Scene Editor Widget, the content changes depending on the type of graphics selected in graphic list on Scene Editor Widget.
+
+.. _curl: http://www.math.umn.edu/~nykamp/m2374/readings/divcurl/
+
+General description of graphics
+-------------------------------
+
+graphics are the building blocks used to create any visualization displayed in the :ref:`sceneviewer widget <Sceneviewer-Widget>`. 
+They are created, edited, re-ordered and deleted from within the :ref:`scene editor widget <Scene-Editor-Widget>`, or via the command line. Most graphics have the following settings in common:
+
+* Coordinate field: This setting has a drop-down menu showing a list of fields that can be selected as the coordinate field for the selected graphic.
+
+* Coordinate System: This setting can be used to render the graphic according to a range of different coordinate systems. This is useful for creating "static" overlays of data on visualizations.
+
+* Boundary mode: This drop-down menu allows you to select a boundary, and automatically only render glyphs on the select boundary of a mesh.
+
+* Select mode: This drop-down menu allows you to select different selection behaviours for the graphic:
+
+  * select_on - The default setting; graphics are able to be selected and selected items are highlighted by rendering in the *default_selected* material.
+  * no_select - No selection or highlighting of the graphic.
+  * draw_selected - only selected items are drawn.
+  * draw_unselected - only unselected items are drawn.
+
+* Wireframe: This checkbox will control whether only the wireframe of the mesh is rendered.
+
+* Material: This drop-down menu allows you to select which material should be used to render the graphic. Materials are defined and edited in the :ref:`material editor Widget <Material-Editor-Widget>`.
+
+* Selected material: This drop-down menu allows you to set which material will be used to render parts of the graphic which are selected.
+
+* Data: This setting has a drop-down menu, allowing you to select which field will be mapped on to the graphic. This enables you to colour the graphic according to the values of some field, for example. The check box also activates the *spectrum* drop-down menu.
+
+* Spectrum: This drop-down menu is used to select which spectrum is to be used to colour the graphical element according to the field selected in the *data* setting. Spectra are edited in the :ref:`spectrum editor widget <Spectrum-Editor-Widget>`.
+
+* Tessellation: Tessellation settings are used to set the level of detail of an object.
+
+.. note::
+
+   The only graphics which do not have a tessellation setting are *node points*, *data points*, and *point*.
+
+* Tessellation field: This setting has a drop-down menu showing a list of fields that can be selected as the tessellation field for the selected graphic.
+
+* Line width: This line editor allows you to set render line width.
+
+* Point size: This line editor allows you to set render point size.
+
+.. _types-of-graphics:
+
+The types of graphics
+---------------------
+
+* **point**
+
+  Point graphics are used to add a single glyph to the scene. 
+
+  * **node points**
+
+    Node points are used to visualize nodes. You can use glyphs to represent node points. There are a range of built-in glyphs in Zinc, and it is possible to create custom glyphs as well. 
+    *Node points* graphics have the following settings in addition to the common ones listed above:
+
+  * **data points**
+
+    Data points are used to visualize data points. Like node points, they can be represented using glyphs. 
+    They have the same settings as *node points*.
+
+  * **element points**
+
+    Element points are used to visualize the discretized points within an element. Elements may be 1, 2 or 3 dimensional, in which case the element points are spaced along the line, across the surface, or throughout the volume according to the chosen *tessellation* object . They have the following specific settings:
+
+* **lines**
 
-The settings editor is where each graphic is set up.
-It contains a number of controls.
+  Lines are used to visualize 1D elements, or the edges of 2D or 3D elements. They are simple, unshaded lines that have a fixed, specified width. They have the following specific settings:
 
-* Subgroup: This drop down menu allows you to select the subgroup of current graphic.
-* Coordinates: This drop down menu allows you to select the coordinate of current graphic.
-* Coord System: This drop down menu allows you to select the coordinate system of current graphic.
-* Boundary Mode: This drop down menu allows you to select the boundary mode of current graphic.
-* Face: This drop down menu allows you to select the face of current graphic.
-* Wireframe: This checkbox allows you to set if the graphic is displayed in a skeletal three-dimensional model in which only lines and vertices are represented.
-* Material: This drop down menu allows you to select material for current graphic.
-* Data field: This drop down menu allows you to select data field for current graphic.
-* Spectrum: This drop down menu allows you to select spectrum for current graphic.
-* Tessellation: This drop down menu allows you to select tessellation for current graphic.
+* **contours**
 
-If the graphic is a line:
+  Contours are used to visualize the same things as lines. They are shaded contours of a specified radius. They have the following specific settings:
 
-* Shape: This drop down menu allows you to select shape for current line graphic.
-* Base size: This text box allows you to set the base size for line graphic, format as number*number.
-* Scale field: This drop down menu allows you to select scale field for current line graphic.
-* Scaling: This text box allows you to set the scaling for line graphic, format as number*number.
+* **surfaces**
 
-If the graphic is a point:
+  Surfaces are used to visualize 2D elements or the faces of 3D elements. They are shaded surfaces of zero thickness that are automatically shaped according to the nodes defining the element they represent. Their level of detail is specified per surface by choosing a *tessellation* object. They have the following specific settings:
 
-* Glyph: This drop down menu allows you to select glyph for current point graphic.
-* Base size: This text box allows you to set the base size for point graphic, format as number*number*number.
-* Scale field: This drop down menu allows you to select scale field for current point graphic.
-* Scaling: This text box allows you to set the scaling for point graphic, format as number*number*number.
-* Label field: This drop down menu allows you to select label field for current point graphic.
-* Sampling mode: This drop down menu allows you to select sampling mode for current point graphic.
+* **streamlines**
 
-API
----
+  Streamlines are a special graphic for visualizing *vector* fields - for example, a fluid flow solution. They can be used to visualize 3, 6 or 9 component vector fields within a 3 dimensional element. 
+  Streamlines will align along their length according to the first vector of a vector field, and across their "width" (eg the width of the *ribbon* or *rectangle* streamline types) to the second vector. 
+  For single vector (3 component) vector fields, the width of the streamlines will align to the curl_ of the vector.
 
-.. autoclass:: opencmiss.zincwidgets.graphicseditorwidget.GraphicsEditorWidget
-   :members:
+  Note that streamlines can be quite expensive to compute; changes to streamline settings in the :ref:`scene editor <Scene-Editor-Widget>` can take several seconds to appear in the 3D window, especially for complex scenes.

docs/index.rst

@@ -7,6 +7,7 @@ Widgets
 -------
 
 .. toctree::
+   :maxdepth: 1
 
    fieldeditorwidget
    graphicseditorwidget

docs/materialeditorwidget.rst

@@ -1,38 +1,60 @@
+.. _Material-Editor-Widget:
+
+======================
 Material Editor Widget
 ======================
 
-The **Material Editor Widget** is a control to add, remove, and modify materials.
+The material editor window is where you define materials to be applied to graphical elements or objects in the graphics window.  
 
 .. _fig-opencmiss-zincwidgets-material-editor-widget:
 
 .. figure:: _images/material-editor-widget.png
    :alt: Material editor widget.
+   :width: 75%
 
    Material editor widget.
 
 Material list
 -------------
 
-The material list displays all currently defined materials; it will always contain the default material if no other materials are defined.
-The two buttons at the top of the window allow you to create or delete materials.
+Along the top of the material editor window are two buttons; create and delete.  You can create a new material, or delete an existing material using these buttons.  
 
-Settings editor
----------------
+Below these buttons is the list of currently defined materials.
+These will contain the default materials, as well as any defined in any comfile that has been run.
 
-Below the material list are controls that allow you to set some general properties of the selected material.
-Ambient Color, Diffuse Color, Emission Color, and Specular Color. 
-You can also adjust the alpha and shininess of the material by entering a number between 0 and 1 or dragging the sliders.
+You can rename the material by double click it.
 
-Preview panel
--------------
+.. figure:: _images/material-editor-rename.png
+   :alt: Material editor rename material.
+   :width: 50%
 
-This panel displays a sphere, shaded with the selected material.
+   Rename material.
+
+Controls
+--------
+
+Below the material list is a panel containing four colour select buttons. These control the ambient, diffuse, emitted and specular colours.
 
-API
----
+* Ambient - The ambient colour is the "unlit" colour, or the colour of parts of the object that are in shadow.
+* Diffuse - This is the overall colour of the material, the colour that the lit parts of the object will appear.
+* Emitted - The emitted colour is the "glow" of a material; this colour will appear in both the lit and unlit parts of the material.
+* Specular - This is the colour of the shine that appears on the material.  This shine appears as a glossy highlight.
 
-.. autoclass:: opencmiss.zincwidgets.materialeditorwidget.MaterialEditorWidget
-   :members:
+.. figure:: _images/material-editor-select-color.png
+   :alt: Material editor select colour.
+   :width: 50%
 
-.. autoclass:: opencmiss.zincwidgets.materialeditorwidget.MaterialModel
-   :members:
+   Select colour.
+
+When you click the Select Colour button, a colour dialog will pop up, and you can select a colour in several ways. The background of these four buttons indicates the colour you choose.
+
+Below the colour editors is the surface editor.  This panel allows you to set the alpha, shininess, and texture properties of the surface of the material being edited.  
+The alpha value sets the transparency of the material.  The shininess sets the "tightness" or size of the specular highlights of a material; generally the higher the shininess, the smaller and harder-edged the highlights.  
+Higher shininess makes a material look glossier.  
+The surface editor also allows you to assign a texture to the material surface - this option is unavailable for now.
+
+Preview panel
+-------------
+
+Below the surface editor is a panel that shows a preview of the currently edited material applied to a sphere. 
+This panel displays a sphere, shaded with the selected material.

docs/modelsourceseditorwidget.rst

@@ -1,3 +1,6 @@
+.. _Model-Sources-Editor-Widget:
+
+===========================
 Model Sources Editor Widget
 ===========================
 
@@ -7,6 +10,7 @@ The **Model Sources Editor Widget** is a control to add and remove source files.
 
 .. figure:: _images/model-sources-editor-widget.png
    :alt: Model sources editor widget.
+   :width: 75%
 
    Model sources editor widget.
 
@@ -27,12 +31,3 @@ For the demonstration dataset we want to load the organ scaffold into the root r
 
 Note: Click the red-colored minus (Remove) icon to remove a file from the assigned region. 
 But this operation is fraught with error and it is best not to use this functionality.
-
-API
----
-
-.. autoclass:: opencmiss.zincwidgets.modelsourceseditorwidget.ModelSourcesEditorWidget
-   :members:
-
-.. autoclass:: opencmiss.zincwidgets.modelsourceseditorwidget.ModelSourcesModel
-   :members:

docs/regioneditorwidget.rst

@@ -1,3 +1,6 @@
+.. _Region-Editor-Widget:
+
+====================
 Region Editor Widget
 ====================
 
@@ -7,6 +10,7 @@ The **Region Editor Widget** is a control to add, remove, and modify the region
 
 .. figure:: _images/region-editor-widget.png
    :alt: Region editor widget.
+   :width: 75%
 
    Region editor widget.
 
@@ -16,13 +20,4 @@ Region Tree
 This tree view shows the region structures. You can create new regions by right-clicking on the parent region of the new region. 
 From the popup menu select the add child region entry. 
 You can rename a region by double-clicking on the region and entering an alpha-numeric value. 
-You can remove a region by right-clicking on the region and select remove region on the popup menu.
-
-API
----
-
-.. autoclass:: opencmiss.zincwidgets.regioneditorwidget.RegionEditorWidget
-   :members:
-
-.. autoclass:: opencmiss.zincwidgets.regioneditorwidget.RegionTreeModel
-   :members:
+You can remove a region by right-clicking on the region and select remove region on the popup menu.

docs/sceneeditorwidget.rst

@@ -1,3 +1,6 @@
+.. _Scene-Editor-Widget:
+
+===================
 Scene Editor Widget
 ===================
 
@@ -7,20 +10,26 @@ The **Scene Editor Widget** is a control to add, remove, and modify the graphics
 
 .. figure:: _images/scene-editor-widget.png
    :alt: Scene editor widget.
+   :width: 75%
 
    Scene editor widget.
 
 Graphics list
 -------------
 
+Along the top of the scene editor window is a region selector that allows you to select the region of current scene.
+
+Below the selector is the list of currently defined graphics.
 The graphics list displays all the defined graphics in the current scene, each with a checkbox in front of it. 
 This checkbox allows you to set whether to display this graphic.
-Above the chart list is a region selector that allows you to select the region of current scene.
-Below the list of graphics, there is a drop-down menu that allows you to add a new graphic.
-There is also a button that allows you to delete the selected graph.
+This graphics list can also be reordered via drag and drop. Graphics at the top have higher display priority.
+The name of the graph shows the graph type followed by the domain type and subgroup field, which can be changed in the settings editor below.
+
+Below the list of graphics, there is a drop-down menu that allows you to add a new graphic, and a button to delete the selected existing graphic.
 
-API
----
 
-.. autoclass:: opencmiss.zincwidgets.sceneeditorwidget.SceneEditorWidget
-   :members:
+Settings editor
+---------------
+Below the graphics list is the settings editor where each graphical setting can be edited. 
+When a graphical setting is selected from the list, all of its editable properties appear in this area. 
+The range of editable properties will vary depending on the :ref:`type of graphics <types-of-graphics>` currently selected.

docs/sceneviewereditorwidget.rst

@@ -0,0 +1,7 @@
+.. _Sceneviewer-Editor-Widget:
+
+=========================
+Sceneviewer Editor Widget
+=========================
+
+The **Sceneviewer Editor Widget** is a widget for editing a displayed OpenGL based scene.

docs/sceneviewerwidget.rst

@@ -1,4 +1,7 @@
-Sceneviewer Editor Widget
-=========================
+.. _Sceneviewer-Widget:
 
-The **Sceneviewer Editor Widget** is a widget for displaying an OpenGL based scene.
+==================
+Sceneviewer Widget
+==================
+
+The **Sceneviewer Widget** is a widget for displaying an OpenGL based scene.