From b1090c10d55bbb6b12d8604812ba610f52b8de7d Mon Sep 17 00:00:00 2001 From: "Mark C. Miller" Date: Fri, 4 Oct 2024 11:29:59 -0700 Subject: [PATCH 01/13] Create check_methoddoc_gen.yaml Create GitHub action for checking MethodDoc.C is generated when functions.rst is changed. --- .github/workflows/check_methoddoc_gen.yaml | 69 ++++++++++++++++++++++ 1 file changed, 69 insertions(+) create mode 100644 .github/workflows/check_methoddoc_gen.yaml diff --git a/.github/workflows/check_methoddoc_gen.yaml b/.github/workflows/check_methoddoc_gen.yaml new file mode 100644 index 00000000000..50e5b15dff0 --- /dev/null +++ b/.github/workflows/check_methoddoc_gen.yaml @@ -0,0 +1,69 @@ +name: Check sync of functions.rst and MethodDoc.C + +on: + pull_request: + paths: + - 'src/doc/python_scripting/functions.rst' + - 'src/visitpy/common/MethodDoc.C' + - 'src/visitpy/common/MethodDoc.h' + +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_script/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 0 ]]; then + if [[ $have_methdoc_c -eq 0 ]]; then + echo "Error: Changes to functions.rst require regeneration of MethodDoc.C (and possibly MethodDoc.h)" + echo " Please follow https://visit-sphinx-github-user-manual.readthedocs.io/en/develop/dev_manual/UpdatingPythonDocStrings.html" + exit 1 + fi + fi + if [[ $have_methdoc_c -ne 0 ]]; then + if [[ $have_func_rst -eq 0 ]]; then + echo "Error: You have made changes directly to a *generated* file, MethodDoc.C." + echo " You must make your changes to functions.rst and regenerate MethodDoc.C (and possibly MethodDoc.h)." + echo " Please follow https://visit-sphinx-github-user-manual.readthedocs.io/en/develop/dev_manual/UpdatingPythonDocStrings.html" + exit 1 + fi + 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 + diff --brief 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 From bc0a3c4f3ee4f7552d806b94adaaf4b780bd0732 Mon Sep 17 00:00:00 2001 From: "Mark C. Miller" Date: Fri, 4 Oct 2024 11:48:43 -0700 Subject: [PATCH 02/13] fix indentation --- .github/workflows/check_methoddoc_gen.yaml | 64 +++++++++++----------- 1 file changed, 32 insertions(+), 32 deletions(-) diff --git a/.github/workflows/check_methoddoc_gen.yaml b/.github/workflows/check_methoddoc_gen.yaml index 50e5b15dff0..b087d1b84a6 100644 --- a/.github/workflows/check_methoddoc_gen.yaml +++ b/.github/workflows/check_methoddoc_gen.yaml @@ -14,48 +14,48 @@ jobs: steps: - name: Set up Python - uses: actions/setup-python@v2 - with: - python-version: '3.9' + uses: actions/setup-python@v2 + with: + python-version: '3.9' - name: Checkout code - uses: actions/checkout@v2 + uses: actions/checkout@v2 - name: Get Changed Files (for PRs) - id: changed-files - uses: tj-actions/changed-files@v42 - with: - separator: ' ' + 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_script/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 0 ]]; then - if [[ $have_methdoc_c -eq 0 ]]; then - echo "Error: Changes to functions.rst require regeneration of MethodDoc.C (and possibly MethodDoc.h)" - echo " Please follow https://visit-sphinx-github-user-manual.readthedocs.io/en/develop/dev_manual/UpdatingPythonDocStrings.html" - exit 1 - fi + 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_script/functions.rst" ]]; then + have_func_rst=1 + elif [[ "$f" == "src/visitpy/common/MethodDoc.C" ]]; then + have_methdoc_c=1 fi - if [[ $have_methdoc_c -ne 0 ]]; then - if [[ $have_func_rst -eq 0 ]]; then - echo "Error: You have made changes directly to a *generated* file, MethodDoc.C." - echo " You must make your changes to functions.rst and regenerate MethodDoc.C (and possibly MethodDoc.h)." - echo " Please follow https://visit-sphinx-github-user-manual.readthedocs.io/en/develop/dev_manual/UpdatingPythonDocStrings.html" - exit 1 - fi + done + if [[ $have_func_rst -ne 0 ]]; then + if [[ $have_methdoc_c -eq 0 ]]; then + echo "Error: Changes to functions.rst require regeneration of MethodDoc.C (and possibly MethodDoc.h)" + echo " Please follow https://visit-sphinx-github-user-manual.readthedocs.io/en/develop/dev_manual/UpdatingPythonDocStrings.html" + exit 1 fi + fi + if [[ $have_methdoc_c -ne 0 ]]; then + if [[ $have_func_rst -eq 0 ]]; then + echo "Error: You have made changes directly to a *generated* file, MethodDoc.C." + echo " You must make your changes to functions.rst and regenerate MethodDoc.C (and possibly MethodDoc.h)." + echo " Please follow https://visit-sphinx-github-user-manual.readthedocs.io/en/develop/dev_manual/UpdatingPythonDocStrings.html" + exit 1 + fi + fi - name: Check Generated MethodDoc.C - run: | + run: | cp src/visitpy/common/MethodDoc.C src/visitpy/common/MethodDoc.C.orig pushd src/doc ./functions_to_plain_py.py From e7486df6911c5224d7f91c392edebebd054f2562 Mon Sep 17 00:00:00 2001 From: "Mark C. Miller" Date: Fri, 4 Oct 2024 12:50:58 -0700 Subject: [PATCH 03/13] ws change to trigger ci --- src/doc/python_scripting/functions.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/src/doc/python_scripting/functions.rst b/src/doc/python_scripting/functions.rst index 6ac590a27e8..2fab1c879dd 100644 --- a/src/doc/python_scripting/functions.rst +++ b/src/doc/python_scripting/functions.rst @@ -1,5 +1,6 @@ + Functions ========= From 3964b5db5d0b15d08160c552a09991cf7bd42f00 Mon Sep 17 00:00:00 2001 From: "Mark C. Miller" Date: Fri, 4 Oct 2024 12:54:59 -0700 Subject: [PATCH 04/13] debug workflow --- .github/workflows/check_methoddoc_gen.yaml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/workflows/check_methoddoc_gen.yaml b/.github/workflows/check_methoddoc_gen.yaml index b087d1b84a6..f240d1bba65 100644 --- a/.github/workflows/check_methoddoc_gen.yaml +++ b/.github/workflows/check_methoddoc_gen.yaml @@ -29,6 +29,7 @@ jobs: - name: Check synced files run: | + set -x have_func_rst=0 have_methdoc_c=0 for f in ${{ steps.changed-files.outputs.all_changed_files }}; do @@ -61,6 +62,7 @@ jobs: ./functions_to_plain_py.py 2to3 -p PY_RST_FUNCTIONS_TO_PYTHON.py ./functions_to_method_doc.py + popd diff --brief 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" From 580c2e556cc1c5e83baece4476e124709d82f8b8 Mon Sep 17 00:00:00 2001 From: "Mark C. Miller" Date: Fri, 4 Oct 2024 12:58:18 -0700 Subject: [PATCH 05/13] fix shell if tests --- .github/workflows/check_methoddoc_gen.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/check_methoddoc_gen.yaml b/.github/workflows/check_methoddoc_gen.yaml index f240d1bba65..756a0fd7d9e 100644 --- a/.github/workflows/check_methoddoc_gen.yaml +++ b/.github/workflows/check_methoddoc_gen.yaml @@ -33,9 +33,9 @@ jobs: have_func_rst=0 have_methdoc_c=0 for f in ${{ steps.changed-files.outputs.all_changed_files }}; do - if [[ "$f" == "src/doc/python_script/functions.rst" ]]; then + if [ "$f" = "src/doc/python_script/functions.rst" ]; then have_func_rst=1 - elif [[ "$f" == "src/visitpy/common/MethodDoc.C" ]]; then + elif [ "$f" = "src/visitpy/common/MethodDoc.C" ]; then have_methdoc_c=1 fi done From 93d2395aebbe16b7894b0dae2cfdf3b4bf8ca3e1 Mon Sep 17 00:00:00 2001 From: "Mark C. Miller" Date: Fri, 4 Oct 2024 13:07:41 -0700 Subject: [PATCH 06/13] fix typo --- .github/workflows/check_methoddoc_gen.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/check_methoddoc_gen.yaml b/.github/workflows/check_methoddoc_gen.yaml index 756a0fd7d9e..42d77d73207 100644 --- a/.github/workflows/check_methoddoc_gen.yaml +++ b/.github/workflows/check_methoddoc_gen.yaml @@ -33,7 +33,7 @@ jobs: have_func_rst=0 have_methdoc_c=0 for f in ${{ steps.changed-files.outputs.all_changed_files }}; do - if [ "$f" = "src/doc/python_script/functions.rst" ]; then + 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 From cd35963c0d560bbde0669b5f9d2aa819db643529 Mon Sep 17 00:00:00 2001 From: "Mark C. Miller" Date: Fri, 4 Oct 2024 13:10:03 -0700 Subject: [PATCH 07/13] ws change to trigger ci --- .github/workflows/check_methoddoc_gen.yaml | 1 - src/visitpy/common/MethodDoc.C | 1 + 2 files changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/check_methoddoc_gen.yaml b/.github/workflows/check_methoddoc_gen.yaml index 42d77d73207..a6dbdc48e29 100644 --- a/.github/workflows/check_methoddoc_gen.yaml +++ b/.github/workflows/check_methoddoc_gen.yaml @@ -29,7 +29,6 @@ jobs: - name: Check synced files run: | - set -x have_func_rst=0 have_methdoc_c=0 for f in ${{ steps.changed-files.outputs.all_changed_files }}; do diff --git a/src/visitpy/common/MethodDoc.C b/src/visitpy/common/MethodDoc.C index 146de934274..4c5a564b545 100644 --- a/src/visitpy/common/MethodDoc.C +++ b/src/visitpy/common/MethodDoc.C @@ -3,6 +3,7 @@ // details. No copyright assignment is required to contribute to VisIt. + // *************************************************************************** // Warning: Autogenerated by /src/doc/functions_to_method_doc.py // ALL CHANGES TO THIS FILE WILL BE OVERWRITTEN! From 762492d9adb735a8b4980aafed7bed9c68279b85 Mon Sep 17 00:00:00 2001 From: "Mark C. Miller" Date: Fri, 4 Oct 2024 13:15:55 -0700 Subject: [PATCH 08/13] add doc entry --- .github/workflows/check_methoddoc_gen.yaml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/.github/workflows/check_methoddoc_gen.yaml b/.github/workflows/check_methoddoc_gen.yaml index a6dbdc48e29..c5abed02ef3 100644 --- a/.github/workflows/check_methoddoc_gen.yaml +++ b/.github/workflows/check_methoddoc_gen.yaml @@ -1,5 +1,9 @@ name: Check sync of functions.rst and MethodDoc.C +# +# See documentation at bottom of file +# + on: pull_request: paths: From 412cf785c53c9081d0d238e37ec7e256a025ddc7 Mon Sep 17 00:00:00 2001 From: "Mark C. Miller" Date: Fri, 4 Oct 2024 13:19:18 -0700 Subject: [PATCH 09/13] debug diff --- .github/workflows/check_methoddoc_gen.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/check_methoddoc_gen.yaml b/.github/workflows/check_methoddoc_gen.yaml index c5abed02ef3..d28e5d6172f 100644 --- a/.github/workflows/check_methoddoc_gen.yaml +++ b/.github/workflows/check_methoddoc_gen.yaml @@ -66,7 +66,7 @@ jobs: 2to3 -p PY_RST_FUNCTIONS_TO_PYTHON.py ./functions_to_method_doc.py popd - diff --brief src/visitpy/common/MethodDoc.C src/visitpy/common/MethodDoc.C.orig + 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" From 3315247a3efde76ad9cca6a22d1d61fa749c10af Mon Sep 17 00:00:00 2001 From: "Mark C. Miller" Date: Fri, 4 Oct 2024 13:21:47 -0700 Subject: [PATCH 10/13] undu change to MethodDoc.C --- src/visitpy/common/MethodDoc.C | 1 - 1 file changed, 1 deletion(-) diff --git a/src/visitpy/common/MethodDoc.C b/src/visitpy/common/MethodDoc.C index c4378f7ed96..0c34bb9981d 100644 --- a/src/visitpy/common/MethodDoc.C +++ b/src/visitpy/common/MethodDoc.C @@ -3,7 +3,6 @@ // details. No copyright assignment is required to contribute to VisIt. - // *************************************************************************** // Warning: Autogenerated by /src/doc/functions_to_method_doc.py // ALL CHANGES TO THIS FILE WILL BE OVERWRITTEN! From 6a1a28facce0eb0f947c90e8e2984dfce7a4a37b Mon Sep 17 00:00:00 2001 From: "Mark C. Miller" Date: Fri, 4 Oct 2024 13:26:24 -0700 Subject: [PATCH 11/13] sync the files --- .github/workflows/check_methoddoc_gen.yaml | 6 ++++++ src/doc/python_scripting/functions.rst | 3 +-- src/visitpy/common/MethodDoc.C | 2 +- 3 files changed, 8 insertions(+), 3 deletions(-) diff --git a/.github/workflows/check_methoddoc_gen.yaml b/.github/workflows/check_methoddoc_gen.yaml index d28e5d6172f..a071d745083 100644 --- a/.github/workflows/check_methoddoc_gen.yaml +++ b/.github/workflows/check_methoddoc_gen.yaml @@ -72,3 +72,9 @@ jobs: 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 diff --git a/src/doc/python_scripting/functions.rst b/src/doc/python_scripting/functions.rst index c6124985063..0b291a218d2 100644 --- a/src/doc/python_scripting/functions.rst +++ b/src/doc/python_scripting/functions.rst @@ -1,6 +1,5 @@ - Functions ========= @@ -10464,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" From c994c556afbc195f3cb991f410bb85edf6b97017 Mon Sep 17 00:00:00 2001 From: "Mark C. Miller" Date: Fri, 4 Oct 2024 13:31:51 -0700 Subject: [PATCH 12/13] document action --- .github/workflows/check_methoddoc_gen.yaml | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/.github/workflows/check_methoddoc_gen.yaml b/.github/workflows/check_methoddoc_gen.yaml index a071d745083..9c678573c9a 100644 --- a/.github/workflows/check_methoddoc_gen.yaml +++ b/.github/workflows/check_methoddoc_gen.yaml @@ -73,8 +73,22 @@ jobs: 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 +# 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. +# From 540b585b174b66e1365d5a636ba7177c60f7b6e0 Mon Sep 17 00:00:00 2001 From: "Mark C. Miller" Date: Fri, 4 Oct 2024 13:45:12 -0700 Subject: [PATCH 13/13] rm MethodDoc.h and simplify --- .github/workflows/check_methoddoc_gen.yaml | 19 ++++--------------- 1 file changed, 4 insertions(+), 15 deletions(-) diff --git a/.github/workflows/check_methoddoc_gen.yaml b/.github/workflows/check_methoddoc_gen.yaml index 9c678573c9a..8ecff775a4e 100644 --- a/.github/workflows/check_methoddoc_gen.yaml +++ b/.github/workflows/check_methoddoc_gen.yaml @@ -9,7 +9,6 @@ on: paths: - 'src/doc/python_scripting/functions.rst' - 'src/visitpy/common/MethodDoc.C' - - 'src/visitpy/common/MethodDoc.h' jobs: check-sync: @@ -42,20 +41,10 @@ jobs: have_methdoc_c=1 fi done - if [[ $have_func_rst -ne 0 ]]; then - if [[ $have_methdoc_c -eq 0 ]]; then - echo "Error: Changes to functions.rst require regeneration of MethodDoc.C (and possibly MethodDoc.h)" - echo " Please follow https://visit-sphinx-github-user-manual.readthedocs.io/en/develop/dev_manual/UpdatingPythonDocStrings.html" - exit 1 - fi - fi - if [[ $have_methdoc_c -ne 0 ]]; then - if [[ $have_func_rst -eq 0 ]]; then - echo "Error: You have made changes directly to a *generated* file, MethodDoc.C." - echo " You must make your changes to functions.rst and regenerate MethodDoc.C (and possibly MethodDoc.h)." - echo " Please follow https://visit-sphinx-github-user-manual.readthedocs.io/en/develop/dev_manual/UpdatingPythonDocStrings.html" - exit 1 - fi + 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