Create check_methoddoc_gen.yaml (#19879)

.github/workflows/check_methoddoc_gen.yaml

@@ -0,0 +1,83 @@
+name: Check sync of functions.rst and MethodDoc.C
+
+#
+# See documentation at bottom of file
+#
+
+on:
+  pull_request:
+    paths:
+      - 'src/doc/python_scripting/functions.rst'
+      - 'src/visitpy/common/MethodDoc.C'
+
+jobs:
+  check-sync:
+    runs-on: ubuntu-latest
+
+    steps:
+
+    - name: Set up Python
+      uses: actions/setup-python@v2
+      with:
+        python-version: '3.9'
+
+    - name: Checkout code
+      uses: actions/checkout@v2
+
+    - name: Get Changed Files (for PRs)
+      id: changed-files
+      uses: tj-actions/changed-files@v42
+      with:
+        separator: ' '
+
+    - name: Check synced files
+      run: |
+        have_func_rst=0
+        have_methdoc_c=0
+        for f in ${{ steps.changed-files.outputs.all_changed_files }}; do
+          if [ "$f" = "src/doc/python_scripting/functions.rst" ]; then
+            have_func_rst=1
+          elif [ "$f" = "src/visitpy/common/MethodDoc.C" ]; then
+            have_methdoc_c=1
+          fi
+        done
+        if [[ $have_func_rst -ne $have_methdoc_c ]]; then
+          echo "Error: MethodDoc.C (and possibly MethodDoc.h) should be regenerated from functions.rst"
+          echo "       Please follow https://visit-sphinx-github-user-manual.readthedocs.io/en/develop/dev_manual/UpdatingPythonDocStrings.html"
+          exit 1
+        fi
+
+    - name: Check Generated MethodDoc.C
+      run: |
+         cp src/visitpy/common/MethodDoc.C src/visitpy/common/MethodDoc.C.orig
+         pushd src/doc
+         ./functions_to_plain_py.py
+         2to3 -p PY_RST_FUNCTIONS_TO_PYTHON.py
+         ./functions_to_method_doc.py
+         popd
+         diff src/visitpy/common/MethodDoc.C src/visitpy/common/MethodDoc.C.orig
+         if [ $? -ne 0 ]; then
+            echo "Error: MethodDoc.C does not appear to have been generated from functions.rst"
+            echo "       Please follow https://visit-sphinx-github-user-manual.readthedocs.io/en/develop/dev_manual/UpdatingPythonDocStrings.html"
+            exit 1
+         fi
+
+#
+# Documentation of this action
+#
+# This action is designed to catch cases where developers make inconsistent changes to
+# functions.rst and MethodDoc.C. MethodDoc.C is ordinarily *generated* from functions.rst
+# So, developers should just edit functions.rst and then follow the documentation
+# https://visit-sphinx-github-user-manual.readthedocs.io/en/develop/dev_manual/UpdatingPythonDocStrings.html
+# to regenerate MethodDoc.C.
+#
+# The logic in this action only gets triggered if any of the files listed as `path` members of
+# `the pull_request` action are involved. Next, if any those files are involved, it then examines
+# the list of ALL changed files in the PR to check if functions.rst is invovled and if MethodDoc.C
+# is involved.
+#
+# If either one or the other is involved but not both, it fails with an error message.
+#
+# If both are involved, it then tries to perform the MethodDoc.C generation and confirm the
+# result is what is being committed. If not, it fails also.
+#

src/doc/python_scripting/functions.rst

@@ -178,11 +178,15 @@ variableName : string
 
 inheritSIL : integer
     An integer flag indicating whether the plot should inherit the
-    active plot's SIL restriction.
+    active plot's SIL restriction. A zero value indicates that the SIL
+    should **not** be inherited. A non-zero value indicates that the SIL
+    should be inherited.
 
 applyOperators : integer
     An integer flag indicating whether the operators from the active
-    plot should be applied to the new plot.
+    plot should be applied to the new plot. A zero value indicates that
+    the operators should **not** be applied. A non-zero value indicates that
+    the operators should be applied.
 
 return type : CLI_return_t
     The AddPlot function returns an integer value of 1 for success and 0 for
@@ -4036,7 +4040,7 @@ return type : tuple of strings
   DrawPlots()
   mats = GetMaterials()
   for m in mats[:-1]:
-      TurnMaterialOff(m)
+      TurnMaterialsOff(m)
 
 
 GetMeshManagementAttributes
@@ -4341,14 +4345,16 @@ return type : dictionary
     For example, a Curve plot will return the xy pairs that comprise the curve.
     The tuple is arranged <x1, y1, x2, y2, ..., xn, yn>.
 
-    For time queries that create multiple curves, e.g. Time Pick with multiple variables, the dictionary contains a 'Curves' object, and each curve is referenced by it's associated variable name.
-    This was introduced in VisIt 3.4.1.
+    For time queries that create multiple curves, e.g. Time Pick with multiple
+    variables, the dictionary contains a 'Curves' object, and each curve is
+    referenced by it's associated variable name. This was introduced in
+    VisIt 3.4.1.
 
-
-**Single Curve Example:**
+**Example:**
 
 ::
 
+  # Single curve example
   #% visit -cli
   OpenDatabase("/usr/gapps/visit/data/rect2d.silo")
   AddPlot("Pseudocolor", "d")
@@ -4359,10 +4365,7 @@ return type : dictionary
   lineout = info["Curve"]
   print("The first lineout point is: [%g, %g] " % lineout[0], lineout[1])
 
-**Multiple Curve Example:**
-
-::
-
+  # Multiple curve example
   #% visit -cli
   OpenDatabase("/usr/gapps/visit/data/wave.visit")
   AddPlot("Pseudocolor", "pressure")

src/visitpy/common/MethodDoc.C

@@ -178,10 +178,14 @@ const char *visit_AddPlot_doc =
 "    A valid variable name for the open database.\n"
 "inheritSIL : integer\n"
 "    An integer flag indicating whether the plot should inherit the\n"
-"    active plot's SIL restriction.\n"
+"    active plot's SIL restriction. A zero value indicates that the SIL\n"
+"    should **not** be inherited. A non-zero value indicates that the SIL\n"
+"    should be inherited.\n"
 "applyOperators : integer\n"
 "    An integer flag indicating whether the operators from the active\n"
-"    plot should be applied to the new plot.\n"
+"    plot should be applied to the new plot. A zero value indicates that\n"
+"    the operators should **not** be applied. A non-zero value indicates that\n"
+"    the operators should be applied.\n"
 "\n"
 "\n"
 "Returns:\n"
@@ -3652,12 +3656,9 @@ const char *visit_GetLastMessage_doc =
 "\n"
 "GetLastMessage() -> (message, severity)\n"
 "GetLastMessage(int-clr) -> (message, severity)\n"
-"\n"
-"\n"
 "Returns:\n"
-"\n"
-"    GetLastMessage returns a tuple containing 2 strings, the last message and its severity.\n"
-"    If int-clr is present and is non-zero, once the message is retrieved it is also cleared.\n"
+"GetLastMessage returns a tuple containing 2 strings, the last message and its severity.\n"
+"If int-clr is present and is non-zero, once the message is retrieved it is also cleared.\n"
 "\n"
 "\n"
 "Description:\n"
@@ -3892,7 +3893,7 @@ const char *visit_GetMaterials_doc =
 "DrawPlots()\n"
 "mats = GetMaterials()\n"
 "for m in mats[:-1]:\n"
-"    TurnMaterialOff(m)\n"
+"    TurnMaterialsOff(m)\n"
 ;
 const char *visit_GetMeshManagementAttributes_doc = 
 "GetMeshManagementAttributes\n"
@@ -4192,8 +4193,9 @@ const char *visit_GetPlotInformation_doc =
 "VisIt 3.4.1.\n"
 "\n"
 "\n"
-"Single Curve Example:\n"
+"Example:\n"
 "\n"
+"# Single curve example\n"
 "#% visit -cli\n"
 "OpenDatabase(\"/usr/gapps/visit/data/rect2d.silo\")\n"
 "AddPlot(\"Pseudocolor\", \"d\")\n"
@@ -4203,9 +4205,7 @@ const char *visit_GetPlotInformation_doc =
 "info = GetPlotInformation()\n"
 "lineout = info[\"Curve\"]\n"
 "print(\"The first lineout point is: [%g, %g] \" % lineout[0], lineout[1])\n"
-"\n"
-"Multiple Curve Example:\n"
-"\n"
+"# Multiple curve example\n"
 "#% visit -cli\n"
 "OpenDatabase(\"/usr/gapps/visit/data/wave.visit\")\n"
 "AddPlot(\"Pseudocolor\", \"pressure\")\n"