Python doc adjustments (#4756)

* Doc and adjustments of project.py

* Doc and adjustments view.py

* Python doc cleanup

* Python : Add copy of files to deployment folder

* Python : Several updates to doc

* Python : Limit line lenghts

* Minor adjustments

ApplicationCode/GrpcInterface/Python/doc/make_and_copy.bat

@@ -0,0 +1,39 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd
+
+REM Copy files to deployment folder using second parameter
+REM Example "d:\gitroot\ResInsight-UserDocumentation\content\scripting"
+xcopy /Y build\markdown %2

ApplicationCode/GrpcInterface/Python/doc/source/PythonExamples.rst

@@ -10,70 +10,85 @@ This pages is created based on the content in the **PythonExamples** folder loca
  
 
 AllCases
-------
+--------
 .. literalinclude:: ../../rips/PythonExamples/AllCases.py
 
 AppInfo
-------
+-------
 .. literalinclude:: ../../rips/PythonExamples/AppInfo.py
 
 CaseGridGroup
-------
+-------------
 .. literalinclude:: ../../rips/PythonExamples/CaseGridGroup.py
 
 CaseInfoStreamingExample
-------
+------------------------
 .. literalinclude:: ../../rips/PythonExamples/CaseInfoStreamingExample.py
 
 CommandExample
-------
+--------------
 .. literalinclude:: ../../rips/PythonExamples/CommandExample.py
+
 ErrorHandling
-------
+-------------
 .. literalinclude:: ../../rips/PythonExamples/ErrorHandling.py
+
 ExportSnapshots
-------
+---------------
 .. literalinclude:: ../../rips/PythonExamples/ExportSnapshots.py
+
 GridInformation
-------
+---------------
 .. literalinclude:: ../../rips/PythonExamples/GridInformation.py
+
 InputPropTestAsync
-------
+------------------
 .. literalinclude:: ../../rips/PythonExamples/InputPropTestAsync.py
+
 InputPropTestSync
-------
+-----------------
 .. literalinclude:: ../../rips/PythonExamples/InputPropTestSync.py
+
 InstanceExample
-------
+---------------
 .. literalinclude:: ../../rips/PythonExamples/InstanceExample.py
 
 LaunchWithCommandLineOptions
-------
+----------------------------
 .. literalinclude:: ../../rips/PythonExamples/LaunchWithCommandLineOptions.py
+
 SelectedCases
-------
+-------------
 .. literalinclude:: ../../rips/PythonExamples/SelectedCases.py
+
 SetCellResult
-------
+-------------
 .. literalinclude:: ../../rips/PythonExamples/SetCellResult.py
+
 SetFlowDiagnosticsResult
-------
+------------------------
 .. literalinclude:: ../../rips/PythonExamples/SetFlowDiagnosticsResult.py
+
 SetGridProperties
-------
+-----------------
 .. literalinclude:: ../../rips/PythonExamples/SetGridProperties.py
+
 SoilAverageAsync
-------
+----------------
 .. literalinclude:: ../../rips/PythonExamples/SoilAverageAsync.py
+
 SoilAverageSync
-------
+---------------
 .. literalinclude:: ../../rips/PythonExamples/SoilAverageSync.py
+
 SoilPorvAsync
-------
+-------------
 .. literalinclude:: ../../rips/PythonExamples/SoilPorvAsync.py
+
 SoilPorvSync
-------
+------------
 .. literalinclude:: ../../rips/PythonExamples/SoilPorvSync.py
+
 ViewExample
-------
+-----------
 .. literalinclude:: ../../rips/PythonExamples/ViewExample.py

ApplicationCode/GrpcInterface/Python/doc/source/rips.rst

@@ -1,7 +1,7 @@
 Instance Module
 ===============
 
-.. autoclass:: rips.Instance
+.. autoclass:: rips.instance.Instance
     :members:
 
 Example
@@ -14,7 +14,7 @@ Example
 	
 Case Module
 ===========
-.. autoclass:: rips.Case
+.. autoclass:: rips.case.Case
     :members:
 
 Example
@@ -25,23 +25,10 @@ Example
 	:lines: 5-
 	:emphasize-lines: 5
 	
-Commands Module
-===============
-	
-.. autoclass:: rips.Commands
-    :members:
-    :undoc-members:
-	
-Example
--------
-.. literalinclude:: ../../rips/PythonExamples/CommandExample.py
-	:language: python
-	:lines: 5-
-	
 Grid Module
 ===========
 
-.. autoclass:: rips.Grid
+.. autoclass:: rips.grid.Grid
     :members:
 
 Example
@@ -60,26 +47,21 @@ Example
 GridCaseGroup Module
 ====================
 
-.. autoclass:: rips.GridCaseGroup
+.. autoclass:: rips.gridcasegroup.GridCaseGroup
     :members:
 
 
 Project Module
 ==============
 
-.. autoclass:: rips.Project
+.. autoclass:: rips.project.Project
     :members:
 
-Properties Module
-=================
-
-.. autoclass:: rips.Properties
-    :members:
 
 View Module
 ===========
 
-.. autoclass:: rips.View
+.. autoclass:: rips.view.View
     :members:
 
 Synchronous Example

ApplicationCode/GrpcInterface/Python/rips/case.py

@@ -277,25 +277,35 @@ class Case(PdmObject):
         ----------------------------| ------------------------------------------------ | -----
         time_step                   | Time step to export for                          | Integer
         well_path_names             | List of well path names                          | List
-        file_split                  | Split type:
+        file_split                  | Controls how export data is split into files     | String enum
-                                     <ul>
+        compdat_export              | Compdat export type                              | String enum
-                                     <li>'UNIFIED_FILE'</li>
-                                     <li>'SPLIT_ON_WELL'</li>
-                                     <li>'SPLIT_ON_WELL_AND_COMPLETION_TYPE'</li>
-                                     </ul>                                             | String enum
-        compdat_export              | Compdat export type:
-                                      <ul>
-                                      <li>'TRANSMISSIBILITIES'</li>
-                                      <li>'WPIMULT_AND_DEFAULT_CONNECTION_FACTORS'</li>
-                                      </ul>                                            | String enum
         include_perforations        | Export perforations?                             | bool
         include_fishbones           | Export fishbones?                                | bool
         fishbones_exclude_main_bore | Exclude main bore when exporting fishbones?      | bool
-        combination_mode            | Combination mode:
+        combination_mode            | Settings for multiple completions in same cell   | String Enum
-                                      <ul>
+
-                                      <li>'INDIVIDUALLY'</li>
+        ##### Enum file_split 
-                                      <li>'COMBINED'</li>
+
-                                      </ul>                                            | String enum
+        Option                              | Description
+        ----------------------------------- | ------------
+        "UNIFIED_FILE"                      | A single file with all combined transmissibilities
+        "SPLIT_ON_WELL"                     | One file for each well with combined transmissibilities
+        "SPLIT_ON_WELL_AND_COMPLETION_TYPE" | One file for each completion type for each well 
+
+        ##### Enum compdat_export 
+
+        Option                                      | Description
+        ------------------------------------------- | ------------
+        "TRANSMISSIBILITIES"                        | Direct export of transmissibilities
+        "WPIMULT_AND_DEFAULT_CONNECTION_FACTORS"    | Include WPIMULT in addition to transmissibilities
+
+        ##### Enum combination_mode 
+
+        Option              | Description
+        ------------------- | ------------
+        "INDIVIDUALLY"      | Exports the different completion types into separate sections
+        "COMBINED"          | Export one combined transmissibility for each cell
+
         """
         if isinstance(well_path_names, str):
             well_path_names = [well_path_names]
@@ -337,7 +347,7 @@ class Case(PdmObject):
         Create Multiple Fractures in one go
 
         Parameter              | Description                               | Type
-        -----------------------| ----------------------------------       -| -----
+        -----------------------| ----------------------------------------- | -----
         template_id            | Id of the template                        | Integer
         well_path_names        | List of well path names                   | List of Strings
         min_dist_from_well_td  | Minimum distance from well TD             | Double
@@ -381,12 +391,16 @@ class Case(PdmObject):
         refinement_i    | Refinment in x-direction               | Integer
         refinement_j    | Refinment in y-direction               | Integer
         refinement_k    | Refinment in z-direction               | Integer
-        split_type      | Type of LGR split:
+        split_type      | Defines how to split LGRS              | String enum
-                          <ul>
+
-                          <li>'LGR_PER_CELL'</li>
+        ##### Enum split_type 
-                          <li>'LGR_PER_COMPLETION'</li>
+
-                          <li>'LGR_PER_WELL'</li>
+        Option                  | Description
-                          </ul>                                  | String enum
+        ------------------------| ------------
+        "LGR_PER_CELL"          | One LGR for each completed cell 
+        "LGR_PER_COMPLETION"    | One LGR for each completion (fracture, perforation, ...)
+        "LGR_PER_WELL"          | One LGR for each well
+
         """
         if isinstance(well_path_names, str):
             well_path_names = [well_path_names]

ApplicationCode/GrpcInterface/Python/rips/gridcasegroup.py

@@ -64,7 +64,8 @@ class GridCaseGroup(PdmObject):
         """ Compute statistics for the given case ids
 
         Arguments:
-            case_ids(list): list of case ids. If this is None all cases in group are included
+            case_ids(list of integers): list of case ids.
+            If this is None all cases in group are included
 
         """
         if case_ids is None:

ApplicationCode/GrpcInterface/Python/rips/instance.py

@@ -208,10 +208,19 @@ class Instance:
 
         Parameter        | Description                                  | Type
         ---------------- | -------------------------------------------- | -----
-        export_type      | Type of export: 'COMPLETIONS', 'SNAPSHOTS'
+        export_type      | String specifying what to export             | String
-                           'PROPERTIES' or 'STATISTICS'                 | String
         path             | Path to folder                               | String
         create_folder    | Create folder if it doesn't exist?           | Boolean
+
+        ##### Enum export_type 
+
+        Option          | Description
+        --------------- | ------------
+        "COMPLETIONS"   |   
+        "SNAPSHOTS"     |
+        "PROPERTIES"    | 
+        "STATISTICS"    | 
+
         """
         return self.__execute_command(setExportFolder=Cmd.SetExportFolderRequest(
             type=export_type, path=path, createFolder=create_folder))
@@ -219,6 +228,7 @@ class Instance:
     def set_main_window_size(self, width, height):
         """
         Set the main window size in pixels
+
         Parameter | Description      | Type
         --------- | ---------------- | -----
         width     | Width in pixels  | Integer

ApplicationCode/GrpcInterface/Python/rips/project.py

@@ -23,7 +23,7 @@ class Project(PdmObject):
     def __init__(self, channel):
         self._project_stub = Project_pb2_grpc.ProjectStub(channel)
         PdmObject.__init__(self, self._project_stub.GetPdmObject(Empty()),
-                    channel)
+                           channel)
 
     def open(self, path):
         """Open a new project from the given path
@@ -98,6 +98,7 @@ class Project(PdmObject):
 
     def replace_source_cases(self, grid_list_file, case_group_id=0):
         """Replace all source cases within a case group
+        
         Arguments:
             grid_list_file (str): path to file containing a list of cases
             case_group_id (int): id of the case group to replace
@@ -108,6 +109,7 @@ class Project(PdmObject):
 
     def create_grid_case_group(self, case_paths):
         """Create a Grid Case Group from a list of cases
+        
         Arguments:
             case_paths (list): list of file path strings
         Returns:
@@ -129,6 +131,7 @@ class Project(PdmObject):
 
     def view(self, view_id):
         """Get a particular view belonging to a case by providing view id
+        
         Arguments:
             id(int): view id
         Returns: a view object
@@ -150,6 +153,7 @@ class Project(PdmObject):
 
     def grid_case_group(self, group_id):
         """Get a particular grid case group belonging to a project
+        
         Arguments:
             groupId(int): group id
 
@@ -163,6 +167,7 @@ class Project(PdmObject):
 
     def export_multi_case_snapshots(self, grid_list_file):
         """Export snapshots for a set of cases
+        
         Arguments:
             grid_list_file (str): Path to a file containing a list of grids to export snapshot for
         """
@@ -172,6 +177,7 @@ class Project(PdmObject):
 
     def export_snapshots(self, snapshot_type='ALL', prefix=''):
         """ Export all snapshots of a given type
+        
         Arguments:
             snapshot_type (str): Enum string ('ALL', 'VIEWS' or 'PLOTS')
             prefix (str): Exported file name prefix
@@ -182,6 +188,7 @@ class Project(PdmObject):
 
     def export_well_paths(self, well_paths=None, md_step_size=5.0):
         """ Export a set of well paths
+        
         Arguments:
             well_paths(list): List of strings of well paths. If none, export all.
             md_step_size(double): resolution of the exported well path
@@ -193,17 +200,33 @@ class Project(PdmObject):
         return self._execute_command(exportWellPaths=Cmd.ExportWellPathRequest(
             wellPathNames=well_paths, mdStepSize=md_step_size))
 
-    def scale_fracture_template(self, template_id, half_length, height, dfactor,
+    def scale_fracture_template(self, template_id, half_length, height,
-                                conductivity):
+                                d_factor, conductivity):
+        """ Scale fracture template parameters
+        
+        Arguments:
+            template_id(int): ID of fracture template
+            half_length (double): Half Length scale factor
+            height (double): Height scale factor
+            d_factor (double): D-factor scale factor
+            conductivity (double): Conductivity scale factor
+        """
         return self._execute_command(
             scaleFractureTemplate=Cmd.ScaleFractureTemplateRequest(
                 id=template_id,
                 halfLength=half_length,
                 height=height,
-                dFactor=dfactor,
+                dFactor=d_factor,
                 conductivity=conductivity))
 
-    def set_fracture_containment(self, fracture_id, top_layer, base_layer):
+    def set_fracture_containment(self, template_id, top_layer, base_layer):
+        """ Set fracture template containment parameters
+        
+        Arguments:
+            template_id(int): ID of fracture template
+            top_layer (int): Top layer containment
+            base_layer (int): Base layer containment
+        """
         return self._execute_command(
             setFractureContainment=Cmd.SetFracContainmentRequest(
-                id=fracture_id, topLayer=top_layer, baseLayer=base_layer))
+                id=template_id, topLayer=top_layer, baseLayer=base_layer))

ApplicationCode/GrpcInterface/Python/rips/view.py

@@ -66,20 +66,22 @@ class View(PdmObject):
             producers=None):
         """Apply a flow diagnostics cell result
 
-        Arguments:
+        Parameter           | Description                                            | Type
-            result_variable (str): String representing the result value
+        ------------------- | ------------------------------------------------------ | -----
-                The valid values are 'TOF', 'Fraction', 'MaxFractionTracer' and 'Communication'.
+        result_variable     | String representing the result value                   | String
-            selection_mode (str): String specifying which tracers to select.
+        selection_mode      | String specifying which tracers to select              | String
-                The valid values are
+        injectors           | List of injector names, used by 'FLOW_TR_BY_SELECTION' | String List
-                - FLOW_TR_INJ_AND_PROD (all injector and producer tracers),
+        producers           | List of injector names, used by 'FLOW_TR_BY_SELECTION' | String List
-                - FLOW_TR_PRODUCERS (all producers)
+
-                - FLOW_TR_INJECTORS (all injectors),
+        ##### Enum compdat_export 
-                - FLOW_TR_BY_SELECTION (specify individual tracers in the
+
-                injectors and producers variables)
+        Option                  | Description
-            injectors (list): List of injector names (strings) to select.
+        ------------------------| ------------
-                Requires selection_mode to be 'FLOW_TR_BY_SELECTION'.
+        "TOF"                   | Time of flight
-            producers (list): List of producer tracers (strings) to select.
+        "Fraction"              | Fraction
-                Requires selection_mode to be 'FLOW_TR_BY_SELECTION'.
+        "MaxFractionTracer"     | Max Fraction Tracer
+        "Communication"         | Communication
+
         """
         if injectors is None:
             injectors = []
@@ -110,6 +112,7 @@ class View(PdmObject):
         return self.case().view(view_id)
 
     def set_time_step(self, time_step):
+        """Set the time step for current view"""
         case_id = self.case().case_id
         return self._execute_command(setTimeStep=Cmd.SetTimeStepParams(
             caseId=case_id, viewId=self.view_id, timeStep=time_step))
@@ -117,6 +120,31 @@ class View(PdmObject):
     def export_sim_well_fracture_completions(self, time_step,
                                              simulation_well_names, file_split,
                                              compdat_export):
+        """Export fracture completions for simulation wells
+
+        Parameter                   | Description                                      | Type
+        ----------------------------| ------------------------------------------------ | -----
+        time_step                   | Time step to export for                          | Integer
+        simulation_well_names       | List of simulation well names                    | List
+        file_split                  | Controls how export data is split into files     | String enum
+        compdat_export              | Compdat export type                              | String enum
+
+        ##### Enum file_split 
+
+        Option                              | Description
+        ----------------------------------- | ------------
+        "UNIFIED_FILE" <b>Default Option</b>| A single file with all transmissibilities
+        "SPLIT_ON_WELL"                     | One file for each well transmissibilities
+        "SPLIT_ON_WELL_AND_COMPLETION_TYPE" | One file for each completion type for each well 
+
+        ##### Enum compdat_export 
+
+        Option                                   | Description
+        -----------------------------------------| ------------
+        "TRANSMISSIBILITIES"<b>Default Option</b>| Direct export of transmissibilities 
+        "WPIMULT_AND_DEFAULT_CONNECTION_FACTORS" | Include export of WPIMULT
+
+        """
         if isinstance(simulation_well_names, str):
             simulation_well_names = [simulation_well_names]
 
@@ -135,6 +163,15 @@ class View(PdmObject):
                              visible_active_cells_value=1,
                              hidden_active_cells_value=0,
                              inactive_cells_value=0):
+        """Export special properties for all visible cells.
+
+        Arguments:
+            export_keyword (string): The keyword to export.
+            Choices: 'FLUXNUM' or 'MULTNUM'. Default: 'FLUXNUM'
+            visible_active_cells_value (int): Value to export forvisible active cells. Default: 1
+            hidden_active_cells_value (int): Value to export for hidden active cells. Default: 0
+            inactive_cells_value (int): Value to export for inactive cells. Default: 0
+        """
         case_id = self.case().case_id
         return self._execute_command(
             exportVisibleCells=Cmd.ExportVisibleCellsRequest(
@@ -149,7 +186,7 @@ class View(PdmObject):
         """ Export the current Eclipse property from the view
 
         Arguments:
-            undefined_value (double):	Value to use for undefined values. Defaults to 0.0
+            undefined_value (double): Value to use for undefined values. Defaults to 0.0
         """
         case_id = self.case().case_id
         return self._execute_command(
@@ -160,10 +197,13 @@ class View(PdmObject):
 
     def export_snapshot(self, prefix=''):
         """ Export snapshot for the current view
+        
         Arguments:
             prefix (str): Exported file name prefix
         """
         case_id = self.case().case_id
         return self._execute_command(
-            exportSnapshots=Cmd.ExportSnapshotsRequest(
+            exportSnapshots=Cmd.ExportSnapshotsRequest(type='VIEWS',
-                type='VIEWS', prefix=prefix, caseId=case_id, viewId=self.view_id))
+                                                       prefix=prefix,
+                                                       caseId=case_id,
+                                                       viewId=self.view_id))