Create check_methoddoc_gen.yaml #12
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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' | |
| - '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_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 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 | |
| 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. | |
| # |