DOCS: Implement python developer documentation including filter examp…

…les and a tutorial (#837) Signed-off-by: Joey Kleingers <[email protected]> Signed-off-by: Michael Jackson <[email protected]> Co-authored-by: Michael Jackson <[email protected]>
BlueQuartzSoftware · Feb 19, 2024 · 2a7b94c · 2a7b94c
1 parent 5b24757
commit 2a7b94c
Show file tree

Hide file tree

Showing 23 changed files with 2,756 additions and 101 deletions.
diff --git a/.all-contributorsrc b/.all-contributorsrc
@@ -66,7 +66,7 @@
     },
     {
       "login": "bpenniebq",
-      "name": "bpenniebq",
+      "name": "Braden Pennie",
       "avatar_url": "https://avatars.githubusercontent.com/u/106270421?v=4",
       "profile": "https://github.com/bpenniebq",
       "contributions": [
@@ -75,7 +75,7 @@
     },
     {
       "login": "john-stone-ics",
-      "name": "john-stone-ics",
+      "name": "John Stone",
       "avatar_url": "https://avatars.githubusercontent.com/u/18195504?v=4",
       "profile": "https://github.com/john-stone-ics",
       "contributions": [
@@ -100,6 +100,15 @@
         "research",
         "data"
       ]
+    },
+    {
+      "login": "ajacksonbq",
+      "name": "Alex Jackson",
+      "avatar_url": "",
+      "profile": "https://github.com/ajackson",
+      "contributions": [
+        "code"
+      ]
     }
   ],
   "contributorsPerLine": 7,

diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -876,21 +876,29 @@ set(PIPELINE_EXAMPLES_DEST_DIR "${PIPELINE_DEST_DIR}/Examples")
 
 if(SIMPLNX_DOWNLOAD_TEST_FILES AND TARGET SimplnxCore AND TARGET ITKImageProcessing AND TARGET OrientationAnalysis)
   add_custom_target(Copy_PorosityAnalysis_Pipelines ALL
-    COMMAND ${CMAKE_COMMAND} -E copy_if_different "${simplnx_SOURCE_DIR}/pipelines/PorosityAnalysis.d3dpipeline" "${PIPELINE_EXAMPLES_DEST_DIR}/PorosityAnalysis.d3dpipeline"
+    COMMAND ${CMAKE_COMMAND} -E copy_if_different "${simplnx_SOURCE_DIR}/pipelines/PorosityAnalysis.d3dpipeline" "${PIPELINE_EXAMPLES_DEST_DIR}/Examples/PorosityAnalysis.d3dpipeline"
     COMMENT "Copying Example Pipelines into Binary Directory"
     COMMAND_EXPAND_LISTS
     VERBATIM
   )
   set_target_properties(Copy_PorosityAnalysis_Pipelines PROPERTIES FOLDER ZZ_COPY_FILES)
 
   add_custom_target(Copy_CAxis_Pipelines ALL
-    COMMAND ${CMAKE_COMMAND} -E copy_if_different "${simplnx_SOURCE_DIR}/pipelines/Combo-EBSD-osc_r0c0.d3dpipeline" "${PIPELINE_EXAMPLES_DEST_DIR}/Combo-EBSD-osc_r0c0.d3dpipeline"
+    COMMAND ${CMAKE_COMMAND} -E copy_if_different "${simplnx_SOURCE_DIR}/pipelines/Combo-EBSD-osc_r0c0.d3dpipeline" "${PIPELINE_EXAMPLES_DEST_DIR}/Examples/Combo-EBSD-osc_r0c0.d3dpipeline"
     COMMENT "Copying Example Pipelines into Binary Directory"
     COMMAND_EXPAND_LISTS
     VERBATIM
   )
   set_target_properties(Copy_CAxis_Pipelines PROPERTIES FOLDER ZZ_COPY_FILES)
 
+  # Install the pipeline files
+  install(FILES
+    "${simplnx_SOURCE_DIR}/pipelines/PorosityAnalysis.d3dpipeline"
+    "${simplnx_SOURCE_DIR}/pipelines/Combo-EBSD-osc_r0c0.d3dpipeline"
+    DESTINATION "pipelines/Examples"
+    COMPONENT Applications
+  )
+
   download_test_data(DREAM3D_DATA_DIR ${DREAM3D_DATA_DIR} ARCHIVE_NAME 6_6_caxis_data.tar.gz SHA512 6c3eefac62aecf3344de735c0df932dd9a2623653f39174ec72402c54e8911402ad9903ae2122bc23ff2dba8c94973b2882715908e1913973dff604b614a5293)
   add_custom_target(Copy_CAxis_Data ALL
     COMMAND ${CMAKE_COMMAND} -E tar xzf "${DREAM3D_DATA_DIR}/TestFiles/6_6_caxis_data.tar.gz" 

diff --git a/src/Plugins/SimplnxCore/docs/GeneratePythonSkeletonFilter.md b/src/Plugins/SimplnxCore/docs/GeneratePythonSkeletonFilter.md
@@ -1,46 +1,47 @@
-# Generate Python Plugin or Python Filter
-
-## Group
-
-Python
+# Generate Python Plugin and/or Filters
 
 ## Description
+The **Generate Python Plugin and/or Filters** is a powerful tool in the DREAM3D-NX environment that allows users to generate or update Python plugins and filter codes. This filter provides an interface for setting up and configuring Python filters within DREAM3D-NX pipelines, either by creating new plugins or by adding to existing ones.
 
-This **Filter** generates the Python skeleton code for a new DREAM3D-NX/SIMPL-NX filters.  These new Python filters can either be written to a newly generated Python plugin, or to an existing Python plugin.
-
-### Generating A New Plugin
-
-If the **Use Existing Plugin** parameter is OFF, then this filter will generate both a new Python skeleton plugin and new Python skeleton filters.
-
-The following parameters are available when **Use Existing Plugin** is OFF:
-
-+ Name of Plugin - The name of the plugin, referred to in the generated code.
-+ Human Name of Plugin - The human-readable version of the plugin name.
-+ Plugin Output Directory - The location on the file system where the plugin will be generated.
-+ Filter Names - The names of filters that will be generated in the new plugin, separated by commas.
-
-### Using An Existing Plugin
+## Usage
 
-If the **Use Existing Plugin** parameter is ON, then this filter will generate new Python skeleton filters in an existing plugin.  If the existing plugin was created manually and NOT created using this filter, some additional edits will need to be done in a few of the other plugin files.
+### Configuration
+The filter requires several parameters to be set, which dictate whether a new plugin is created or an existing one is modified. Key parameters include:
 
-The following parameters are available when **Use Existing Plugin** is ON:
+- `Use Existing Plugin`: A flag indicating whether to modify an existing plugin.
+- `Name of Plugin`: The name of the plugin.
+- `Human Name of Plugin`: A human-readable name for the plugin.
+- `Existing Plugin Location`: The directory where the existing plugin is located (for updates).
+- `Plugin Output Directory`: The directory where the new plugin will be stored.
+- `Filter Names`: A list of filter names to be included in the plugin, separated by commas.
 
-+ Existing Plugin Location - The file system path where the existing plugin is located.
-+ Filter Names - The names of filters that will be generated in the existing plugin, separated by commas.
+### Generating a New Plugin
+To generate a new Python plugin:
+1. Set `Use Existing Plugin` to `Off`.
+2. Provide a `Name of Plugin`, `Human Name of Plugin`, `Plugin Output Directory`, and a list of `Filter Names`.
+3. Execute the filter. It will generate the necessary plugin structure and files in the specified output directory.
 
-**NOTE:** This option searches the existing plugin's **\_\_init\_\_.py** and **Plugin.py** files for the following comment tokens:
+### Updating an Existing Plugin
+To add filters to an existing Python plugin:
+1. Set `Use Existing Plugin` to `On`.
+2. Provide the `Existing Plugin Location` where the existing plugin is located.
+3. Provide the `Name of Plugin`, `Human Name of Plugin`, and the list of `Filter Names` you wish to add.
+4. Execute the filter. It will update the existing plugin with the new filters.
 
-1. \# FILTER_INCLUDE_INSERT
-2. \# FILTER_NAME_INSERT
+#### Manual Plugin Creation
 
-Both of these tokens are included in both files for any plugin that was originally generated using this filter.
+If your plugin was not generated using the provided filter but was instead created manually, you may need to perform additional steps to ensure proper integration:
 
-#### What if my plugin was created manually (not generated using this filter)?
+1. **Python Import Statements**:
+   - In the absence of the `# FILTER_INCLUDE_INSERT` token, you must manually insert the Python import statements for the new filters into both the `__init__.py` file and the `Plugin.py` file.
 
-+ If the **\# FILTER_INCLUDE_INSERT** token cannot be found, then the Python import statements for the new filters will need to be manually added to both files.
-+ If the **\# FILTER_NAME_INSERT** token cannot be found, then each filter name will need to be manually added to the **all** and **get_filters** methods in the **\_\_init\_\_.py** and **Plugin.py** files, respectively.
+2. **Filter Name Insertion**:
+   - If the `# FILTER_NAME_INSERT` token is missing, you need to manually add each filter name to specific methods in two files:
+       - In the `__init__.py` file, add to the `all` method.
+       - In the `Plugin.py` file, add to the `get_filters` method. 
 
 ## Example Pipelines
+None
 
 ## License & Copyright
 

diff --git a/src/Plugins/SimplnxCore/src/SimplnxCore/Filters/GeneratePythonSkeletonFilter.cpp b/src/Plugins/SimplnxCore/src/SimplnxCore/Filters/GeneratePythonSkeletonFilter.cpp
@@ -38,7 +38,7 @@ Uuid GeneratePythonSkeletonFilter::uuid() const
 //------------------------------------------------------------------------------
 std::string GeneratePythonSkeletonFilter::humanName() const
 {
-  return "Generate Python Plugin or Python Filter";
+  return "Generate Python Plugin and/or Filters";
 }
 
 //------------------------------------------------------------------------------

diff --git a/src/Plugins/SimplnxCore/wrapping/python/simplnxpy.cpp b/src/Plugins/SimplnxCore/wrapping/python/simplnxpy.cpp
@@ -129,16 +129,17 @@ template <class ParameterT>
 auto BindNumberParameter(py::handle scope, const char* name)
 {
   auto numberParameter = py::class_<ParameterT, IParameter>(scope, name);
-  numberParameter.def(py::init<const std::string&, const std::string&, const std::string&, typename ParameterT::ValueType>());
+  numberParameter.def(py::init<const std::string&, const std::string&, const std::string&, typename ParameterT::ValueType>(), "name"_a, "human_name"_a, "help_text"_a, "default_value"_a);
   return numberParameter;
 }
 
 template <class ParameterT>
 auto BindVectorParameter(py::handle scope, const char* name)
 {
   auto vectorParameter = py::class_<ParameterT, IParameter>(scope, name);
-  vectorParameter.def(py::init<const std::string&, const std::string&, const std::string&, const typename ParameterT::ValueType&>());
-  vectorParameter.def(py::init<const std::string&, const std::string&, const std::string&, const typename ParameterT::ValueType&, const typename ParameterT::NamesType&>());
+  vectorParameter.def(py::init<const std::string&, const std::string&, const std::string&, const typename ParameterT::ValueType&>(), "name"_a, "human_name"_a, "help_text"_a, "default_value"_a);
+  vectorParameter.def(py::init<const std::string&, const std::string&, const std::string&, const typename ParameterT::ValueType&, const typename ParameterT::NamesType&>(), "name"_a, "human_name"_a,
+                      "help_text"_a, "default_value"_a, "names"_a);
   return vectorParameter;
 }
 

diff --git a/wrapping/python/docs/index_template.rst b/wrapping/python/docs/index_template.rst
@@ -27,8 +27,10 @@ by creating a new virtual environment
    Overview
    DataObjects
    Geometry
-   API
+   User_API
+   Developer_API
    Python_Introduction
+   Writing_A_New_Python_Filter
    Reference_Frame_Notes
    ReleaseNotes_110
    ReleaseNotes_120