Create cross links to each parameter type

Update other parts of the documentation

Signed-off-by: Michael Jackson <[email protected]>

wrapping/python/docs/generate_sphinx_docs.cpp

@@ -328,7 +328,7 @@ void GenerateRstFilterDocs()
     std::ofstream rstStream = std::ofstream(rstFilePath, std::ios_base::binary | std::ios_base::trunc);
     if(!rstStream.is_open())
     {
-      std::cout << "ERROR:" << rstFilePath << "\n";
+      std::cout << "ERROR Opening file:" << rstFilePath << "\n *** Aborting filter documentation generation!!\n";
       return;
     }
 
@@ -337,7 +337,13 @@ void GenerateRstFilterDocs()
     rstStream << GenerateUnderline(plugName.size(), '=') << "============="
               << "\n\n";
 
-    rstStream << "   This is the documentation for all filters included in the " << plugName << " module\n\n";
+    rstStream << "   This is the documentation for all filters included in the " << plugName << " module. These filters can"
+              << " be used by importing the appropriate module. Each filter is contained in the module:\n\n"
+              << ".. code:: python\n\n"
+              << "   import " << complex::StringUtilities::toLower(plugName) << "\n"
+              << "   # Instantiate and execute a filter from the module\n"
+              << "   result = " << complex::StringUtilities::toLower(plugName) << ".SomeFilterName.execute(...)\n"
+              << "\n";
 
     rstStream << ".. py:module:: " << plugName << "\n\n";
 
@@ -359,11 +365,15 @@ void GenerateRstFilterDocs()
 
       rstStream << filterClassName << "\n";
       rstStream << GenerateUnderline(filterClassName.size(), '-') << "\n\n";
+      rstStream << ".. index:: pair: Filter Human Names; " << filter->humanName() << "\n";
+      rstStream << ".. index:: pair: Filter Class Names; " << filter->className() << "\n";
+
+      rstStream << "\n";
+      rstStream << "-  **UI Name**: " << filter->humanName() << "\n\n";
 
       rstStream << ".. _" << filterClassName << ":\n";
-      rstStream << ".. py:class:: " << filterClassName << "\n\n";
 
-      rstStream << "   **UI Display Name:** *" << filter->humanName() << "*\n\n";
+      rstStream << ".. py:class:: " << filterClassName << "\n\n";
 
       // Extract out the first paragraph of the Filter's markdown documentation after the ## Description section marker
       const std::filesystem::path docFilePath = fmt::format("{}/docs/{}.md", pluginRootDir, filterClassName);
@@ -409,7 +419,7 @@ void GenerateRstFilterDocs()
       rstStream << "   .. py:method:: Execute(data_structure";
 
       std::stringstream memberStream;
-      memberStream << "      :param complex.DataStructure data_structure: The DataStructure object that holds the data to be processed.\n";
+      memberStream << "      :param DataStructure data_structure: The DataStructure object that holds the data to be processed.\n";
 
       size_t index = 0;
       for(const auto& parameterPair : parameters)
@@ -418,14 +428,15 @@ void GenerateRstFilterDocs()
         rstStream << ", ";
 
         rstStream << parameterPair.first;
-        memberStream << "      :param " << s_ParameterMap[anyParameter->uuid()] << " " << anyParameter->name() << ": " << anyParameter->helpText() << "\n";
+        memberStream << "      :param " << complex::StringUtilities::replace(s_ParameterMap[anyParameter->uuid()], "complex.", "") << " " << anyParameter->name() << ": " << anyParameter->helpText()
+                     << "\n";
         index++;
       }
       rstStream << ")\n\n";
 
       rstStream << memberStream.str();
-      rstStream << "      :return: Returns a complex.Result object that holds any warnings and/or errors that were encountered during execution.\n";
-      rstStream << "      :rtype: complex.Result\n\n";
+      rstStream << "      :return: Returns a :ref:`Result <result>` object that holds any warnings and/or errors that were encountered during execution.\n";
+      rstStream << "      :rtype: :ref:`complex.Result <result>`\n\n";
       rstStream << '\n';
     }
   }

wrapping/python/docs/index_template.rst

@@ -13,8 +13,8 @@ DREAM3D-NX Python Docs
    Overview
    DataObjects
    Geometry
-   Python_Introduction
    API
+   Python_Introduction
    Reference_Frame_Notes
 @PLUGIN_LIST@
 

wrapping/python/docs/source/API.rst

@@ -1,23 +1,32 @@
-complex API Docs
-================
+Filter Parameter Classes
+========================
 
-.. _DataPath:
-.. py:class:: DataPath
+.. _Result:
+.. py:class:: Result
 
-  The DataPath is used to describe a path from the top level of the DataStructure
-  to a target DataObject (Group, Geometry, AttributeMatrix, DataArray)
+   The object that encapsulates any warnings or errors from either preflighting or executing a complex.Filter object.
+   It can be queried for the list of errors or warnings and thus printed if needed.
 
-  .. code:: python
+   .. code:: python
 
-    data_path = cx.DataPath(["Small IN100", "Scan Data", "Confidence Index"])
+      result = cxor.ConvertOrientations.execute(data_structure=data_structure,
+                                          input_orientation_array_path=array_path,
+                                          input_type=0,
+                                          output_orientation_array_name='Quaternions',
+                                          output_type=2)
+      if len(result.errors) != 0:
+         print('Errors: {}', result.errors)
+         print('Warnings: {}', result.warnings)
+      else:
+         print("No errors running the ConvertOrientations")
 
-Parameters 
-----------
+General Parameters 
+------------------
 
 .. _ArrayCreationParameter:
 .. py:class:: ArrayCreationParameter
 
-   This parameter holds a DataPath_ value that points to the location within the DataStructure of where
+   This parameter holds a :ref:`DataPath<DataPath>` value that points to the location within the DataStructure of where
    the DataArray will be created.
 
   .. code:: python
@@ -27,7 +36,7 @@ Parameters
 .. _ArraySelectionParameter:
 .. py:class:: ArraySelectionParameter
 
-   This parameter holds a DataPath_ value that points to the location within the DataStructure of where
+   This parameter holds a :ref:`DataPath<DataPath>` value that points to the location within the DataStructure of where
    the DataArray will be read.
 
   .. code:: python
@@ -53,7 +62,7 @@ Parameters
 
   This class holds the values that are used for comparison in the :ref:`complex.MultiThresholdObjects() <MultiThresholdObjects>` filter.
 
-  :ivar array_path: The DataPath_ to the array to use for this ArrayThreshold
+  :ivar array_path: The :ref:`DataPath<DataPath>` to the array to use for this ArrayThreshold
   :ivar comparison: Int. The comparison operator to use. 0=">", 1="<", 2="=", 3="!="
   :ivar value: Numerical Value. The value for the comparison
 
@@ -83,7 +92,7 @@ Parameters
 .. _AttributeMatrixSelectionParameter:
 .. py:class:: AttributeMatrixSelectionParameter
 
-   This parameter holds a DataPath_ value that points to the location within the DataStructure of a selected AttributeMatrix.
+   This parameter holds a :ref:`DataPath<DataPath>` value that points to the location within the DataStructure of a selected AttributeMatrix.
 
   .. code:: python
 
@@ -94,6 +103,10 @@ Parameters
 
    This parameter holds a True/False value and is represented in the UI with a check box
 
+   .. code:: python
+
+    enable_some_feature = True
+
 .. _CalculatorParameter:
 .. py:class:: CalculatorParameter
 
@@ -122,12 +135,16 @@ Parameters
 
    This parameter holds a single value from a list of choices in the form of an integer. The filter documentation
    should have the valid values to chose from. It is represented in the UI through a ComboBox drop down menu.
-   It can be initialized with an integer type. 
+   It can be initialized with an integer type.
+
+.. code:: python
+
+    a_combo_box_value = 2
 
 .. _DataGroupCreationParameter:
 .. py:class:: DataGroupCreationParameter
 
-   This parameter holds a DataPath_ value that points to the location within the DataStructure of a :ref:`DataGroup<DataGroup>` that will be created
+   This parameter holds a :ref:`DataPath<DataPath>` value that points to the location within the DataStructure of a :ref:`DataGroup<DataGroup>` that will be created
    by the filter.
 
   .. code:: python
@@ -137,7 +154,7 @@ Parameters
 .. _DataGroupSelectionParameter:
 .. py:class:: DataGroupSelectionParameter
 
-   This parameter holds a DataPath_ value that points to the location within the DataStructure of a :ref:`DataGroup<DataGroup>` that will be used in the filter.
+   This parameter holds a :ref:`DataPath<DataPath>` value that points to the location within the DataStructure of a :ref:`DataGroup<DataGroup>` that will be used in the filter.
 
   .. code:: python
 
@@ -155,7 +172,7 @@ Parameters
 .. _DataPathSelectionParameter:
 .. py:class:: DataPathSelectionParameter
 
-   This parameter holds a DataPath_ object that represents an object within the :ref:`DataStructure<DataStructure>`.
+   This parameter holds a :ref:`DataPath<DataPath>` object that represents an object within the :ref:`DataStructure<DataStructure>`.
 
   .. code:: python
 
@@ -200,7 +217,7 @@ Parameters
       The ImportData object has 2 member variables that can be set.
 
    :ivar file_path: Path to the .dream3d file on the file system
-   :ivar data_paths: List of DataPath_ objects. Use the python 'None' value to indicate that you want to read **ALL** the data from file.
+   :ivar data_paths: List of :ref:`DataPath<DataPath>` objects. Use the python 'None' value to indicate that you want to read **ALL** the data from file.
 
 .. code:: python
 
@@ -273,6 +290,9 @@ Parameters
    This parameter represents a file or folder on the local filesystem (or a network mounted filesystem) 
    and can be instantiated using a "PathLike" python class or python string.
 
+.. code:: python
+
+    a_file_system_path = "/The/Path/To/The/File/Or/Directory"
 
 .. _GenerateColorTableParameter:
 .. py:class:: GenerateColorTableParameter
@@ -361,7 +381,7 @@ Parameters
 .. _GeometrySelectionParameter:
 .. py:class:: GeometrySelectionParameter
 
-   This parameter represents the DataPath_ to a valid :ref:`complex.Geometry() <Geometry Descriptions>`
+   This parameter represents the :ref:`DataPath<DataPath>` to a valid :ref:`complex.Geometry() <Geometry Descriptions>`
 
 .. _ImportCSVDataParameter:
 .. py:class:: ImportCSVDataParameter
@@ -442,7 +462,7 @@ Parameters
 
       :ivar input_file: A "PathLike" value to the HDF5 file on the file system
       :ivar datasets: list[ImportHDF5DatasetParameter.DatasetImportInfo, ....]
-      :ivar parent: Optional: The DataPath_ object to a parente group to create the :ref:`DataArray<DataArray>` into. If left blank the :ref:`DataArray<DataArray>` will be created at the top level of the :ref:`DataStructure<DataStructure>`
+      :ivar parent: Optional: The :ref:`DataPath<DataPath>` object to a parente group to create the :ref:`DataArray<DataArray>` into. If left blank the :ref:`DataArray<DataArray>` will be created at the top level of the :ref:`DataStructure<DataStructure>`
 
    .. py:class:: ImportHDF5DatasetParameter.DatasetImportInfo
 
@@ -477,7 +497,7 @@ Parameters
 .. _MultiArraySelectionParameter:
 .. py:class:: MultiArraySelectionParameter
 
-   This parameter represents a list of DataPath_ objects where each DataPath_ object
+   This parameter represents a list of :ref:`DataPath<DataPath>` objects where each :ref:`DataPath<DataPath>` object
    points to a  :ref:`DataArray<DataArray>`
 
    .. code:: python
@@ -487,7 +507,7 @@ Parameters
 .. _MultiPathSelectionParameter:
 .. py:class:: MultiPathSelectionParameter
 
-   This parameter represents a list of DataPath_ objects. The end point of each DataPath_
+   This parameter represents a list of :ref:`DataPath<DataPath>` objects. The end point of each :ref:`DataPath<DataPath>`
    object can be any object in the  :ref:`DataStructure<DataStructure>`
 
    .. code:: python
@@ -498,7 +518,7 @@ Parameters
 .. _NeighborListSelectionParameter:
 .. py:class:: NeighborListSelectionParameter
 
-   This parameter represents a DataPath_ object that has an end point of a 'cx.NeighborList' object
+   This parameter represents a :ref:`DataPath<DataPath>` object that has an end point of a 'cx.NeighborList' object
 
 .. _NumericTypeParameter:
 .. py:class:: NumericTypeParameter
@@ -530,7 +550,13 @@ Numerical Parameters
 --------------------
 
 This group of parameters wrap a specific native C++ numeric type. They can be instantiated
-using standard python integers or decimal values.
+using standard python integers or decimal values. For example.
+
+   .. code:: python
+
+      some_varible = 10
+      other_variable = 22.342
+
 
 .. _Int8Parameter:
 .. py:class:: Int8Parameter
@@ -588,7 +614,12 @@ Numerical Vector Parameters
 
 This group represents a parameter that is being used to gather more than a single
 scalar value from the user. For example, an Origin for an Image Geometry or the 
-dimensions of a DataArray.
+dimensions of a DataArray. It is represented as a list of numerical values. For example
+if a parameter is a 4x1 Float32 value then it would be initialized by:
+
+.. code:: python
+
+   origin = [10.0, 20.0, 33.3, 0.2342]
 
 .. _VectorInt8Parameter:
 .. py:class:: VectorInt8Parameter

wrapping/python/docs/source/DataObjects.rst

@@ -53,7 +53,7 @@ DataPath
 
 A DataPath is a complex class that describes the path to a :ref:`DataObject` within 
 the DataStructure_ . The path is constructed as a python list of string objects.
-For example if we have a top level group called **MyGroup** and a **DataArray** 
+For example if we have a top level group called **MyGroup** and a `DataArray<DataArray>` 
 called *Euler Angles* within that group the **DataPath** object that would be constructed is the following
 
 .. code:: python
@@ -68,7 +68,7 @@ DataArray
 The DataArray is the main class that holds the raw data. It is typically a contiguous
 chunk of memory that is allocated to hold the data that will be processed. The DataArray
 has a few properties that should be well understood by the user before starting to develop
-codes that are based on **complex**. The 
+codes that are based on the `complex <https://www.github.com/bluequartzsoftware/complex>`_ library.
 
 .. image:: Images/DataArray_Explanation.png
    :height: 664
@@ -105,15 +105,20 @@ DataStore
 The DataStore is the C++ object that actually allocates the memory necessary to store
 data in complex/DREAM3D. The Python API is intentially limited to getting a Numpy.View()
 so that python developers can have a consistent well known interace to the DataArray_. The
-programmer will never need to create from scratch a DataStore object. They should be fetched
-from a created DataArray_
+programmer will never need to create from scratch a **DataStore** object. They should be fetched
+from a created DataArray_ by executing the :ref:`Create Data Array <CreateDataArray>` filter.
 
 .. code:: python
 
    # First get the array from the DataStructure
    data_array = data_structure[output_array_path]
    # Get the underlying DataStore object
    data_store = data_array.store
+   # Get the raw data as an Numpy View
+   npdata = data_store.npview()
+   # ------------
+   # The developer can also just inline the above lines into a single line
+   npdata = data_structure[output_array_path].store.npview
 
 .. _AttributeMatrix:
 
@@ -126,10 +131,10 @@ AttributeMatrix
    inserting into the AttributeMatrix:
 
    1) No :ref:`DataGroup` may be inserted into the AttributeMatrix
-   2) All :ref:`DataArray` objects that are inserted into the AttributeMatrix **must** have the same number of tuples.
+   2) All :ref:`DataArray` objects that are inserted into the AttributeMatrix **must** have the same number of *tuples*.
 
 The predominant use of an AttributeMatrix is to group together :ref:`DataArray` objects that represent DataArrays that
-all appear on a specific **Geometry**. For example if you have an **Image Geometry** that is 189 voxels wide (X) by 201
+all appear on a specific **Geometry**. For example if you have an :ref:`Image Geometry <ImageGeom>` that is 189 voxels wide (X) by 201
 voxels tall (Y) by 117 voxels deep (Z), the AttributeMatrix that holds the various DataArrays will have the same dimensions, 
 (but expressed in reverse order, slowest dimension to fastest changing dimension). This ensures that the arrays that represent that data are all fully allocated and accessible. This
 concept can be summarized in the figure below.
@@ -150,3 +155,8 @@ the dimensions are listed as slowest changing (Z) to fastest changing (X) order.
    result = cx.CreateAttributeMatrixFilter.execute(data_structure=data_structure, 
                                                 data_object_path=cx.DataPath(["New Attribute Matrix"]), 
                                                 tuple_dimensions = [[117., 201., 189.]])
+
+Geometry
+----------
+
+Please see the :ref:`Geometry<Geometry Descriptions>` documentation.