diff --git a/.github/workflows/check_methoddoc_gen.yaml b/.github/workflows/check_methoddoc_gen.yaml new file mode 100644 index 00000000000..8ecff775a4e --- /dev/null +++ b/.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. +# diff --git a/src/doc/python_scripting/functions.rst b/src/doc/python_scripting/functions.rst index 4ef020c4e96..846545d5b17 100644 --- a/src/doc/python_scripting/functions.rst +++ b/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 . - 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") diff --git a/src/visitpy/common/MethodDoc.C b/src/visitpy/common/MethodDoc.C index 22714235cb8..0c34bb9981d 100644 --- a/src/visitpy/common/MethodDoc.C +++ b/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"