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 846545d5b17..0b291a218d2 100644 --- a/src/doc/python_scripting/functions.rst +++ b/src/doc/python_scripting/functions.rst @@ -10463,7 +10463,7 @@ format_string : string **Description:** The SetQueryFloatFormat method sets a :ref:`printf-style ` format string that - is used by VisIt's querys to produce textual output. + is used by VisIt's queries to produce textual output. **Example:** diff --git a/src/visitpy/common/MethodDoc.C b/src/visitpy/common/MethodDoc.C index 0c34bb9981d..672a8ec07f2 100644 --- a/src/visitpy/common/MethodDoc.C +++ b/src/visitpy/common/MethodDoc.C @@ -10093,7 +10093,7 @@ const char *visit_SetQueryFloatFormat_doc = "Description:\n" "\n" "The SetQueryFloatFormat method sets a printf-style format string that\n" -"is used by VisIt's querys to produce textual output.\n" +"is used by VisIt's queries to produce textual output.\n" "\n" "\n" "Example:\n"