work on help build for GSAS-II dist & a bit of cleanup

Author: briantoby

.github/workflows/builddocsite.yml

@@ -1,16 +1,21 @@
 # create a documentation web site for GSAS-II from four sources
 #  * HTML tutorials are simply copied
 #  * markdown tutorials (in ./MDtutorials) are formatted with pandoc and are copied over
-#  * HTML help files are copied over from the GSAS-II sources
 #  * sphinx is used to generate HTML from files in ./webdocs
+#  * the tutorials.html file and the */data/index.html files are
+#        created by running scripts/makeGitTutorial
+#  * the help pages are created from the .md file in the MDhelp directory
+#  * this triggers a process that also creates the help files and places
+#        the .html files into the GSAS-II sources
 
-# Also the tutorials.html file and the */data/index.html files are
-#     created by running scripts/makeGitTutorial
+name: build GSAS-II web site w/MD Help
 
-name: build GSAS-II web site
-
-on: [workflow_dispatch] 
-#on: [push, workflow_dispatch]
+#on: [workflow_dispatch] 
+on: 
+  push:
+    branches:  
+      - "main"  
+  workflow_dispatch:
 
 permissions:
   contents: write
@@ -22,6 +27,20 @@ jobs:
     runs-on: ubuntu-latest
     steps:
 
+      - name: Trigger remote workflow to update help files in GSAS-II repo
+        # see below for info on setting this up
+        run: |
+          # config var follows
+          repo_owner="AdvancedPhotonSource" 
+  
+          curl -L \
+            -X POST \
+            -H "Accept: application/vnd.github+json" \
+            -H "Authorization: Bearer ${{ secrets.G2TUT_2_G2_4HELP }}" \
+            -H "X-GitHub-Api-Version: 2022-11-28" \
+            https://api.github.com/repos/$repo_owner/GSAS-II/dispatches \
+            -d '{"event_type": "remote build", "client_payload": {"service": "remote build", "unit": false, "integration": true}}'
+
       - name: Python setup
         uses: actions/setup-python@v3
       - name: Sphinx setup
@@ -30,14 +49,49 @@ jobs:
       - name: pandoc setup
         uses: pandoc/actions/setup@v1
 
+      # MD help stuff
+      - name: install debian chrome
+        run: |
+          set -ex
+          wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
+          sudo apt install ./google-chrome-stable_current_amd64.deb
+   
+#      - name: test newly-installed chrome # for debug
+#        run: |
+#          which google-chrome-stable
+#          google-chrome-stable --version
+#          /usr/bin/google-chrome-stable --headless --disable-gpu --dump-dom https://google.com
+      - name: mkdocs setup
+        run: |
+          pip install mkdocs mkdocs-material python-markdown-math mkdocs-static-i18n
+          pip install mkdocs-to-pdf pymdown-extensions
+
       - name: Checkout
         uses: actions/checkout@v4
+
+      # MD help stuff
+      - name: convert MDhelp
+        run: |
+          cd MDhelp
+          #mkdocs build
+          ENABLE_PDF_EXPORT=1 mkdocs build
+          mv site/GSASII-help.pdf ../docs/
+          # create an anchor index in the help files (only used by Python code)
+          python findMDanchors.py
+          cp -vr site/* ../help/
+          
+      # - name: Upload help artifact  # creates zip file with website contents for debug
+      #   uses: actions/upload-pages-artifact@v3
+      #   with:
+      #       path: MDhelp/site
+      #       name: MDhelp
+      #       retention-days: 1
 
       - name: Get tutorials index from source code
         run: |
           curl -L https://github.com/AdvancedPhotonSource/GSAS-II/raw/master/GSASII/tutorialIndex.py -o scripts/tutorialIndex.py
 
-      - name: convert tutorials
+      - name: convert MarkDown tutorials
         run: |
           cd MDtutorials
           for path in ./*; do
@@ -63,30 +117,23 @@ jobs:
           cd scripts
           python makeGitTutorial.py ..
 
-#      - name: Note changed files
-#        run: |
-#            git add tutorials.html
-#            git add */data/index.html
-#            git status
-#            git commit -m"changes from automated build of tutorials"
-#      - name: Push changes
-#        uses: ad-m/github-push-action@master
-
       - name: Sphinx build
         run: |
           sphinx-build webdocs .  # place output into root dir
           cp webdocs/_static/fix.css _static/fix.css # should be done by sphinx
 
+      # to be replaced by MD help stuff
       # get the help pages from the GSAS-II sources into the web site
-      - name: Get GSAS-II
-        run: |
-          git clone --depth 1 https://github.com/AdvancedPhotonSource/GSAS-II.git _gsas2
-      - name: move help into site
-        run: |
-          mv _gsas2/GSASII/help ./help
+      # - name: Get GSAS-II
+      #   run: |
+      #     git clone --depth 1 https://github.com/AdvancedPhotonSource/GSAS-II.git _gsas2
+      # - name: move help into site
+      #   run: |
+      #     mv _gsas2/GSASII/help ./help
+
       - name: Get rid of the rest of the GSAS-II files & other stuff not needed on web
         run: |
-          rm -rf _gsas2 webdocs scripts MDtutorials
+          rm -rf webdocs scripts MDtutorials MDhelp
         
       - name: Upload artifact  # creates zip file with website contents
         uses: actions/upload-pages-artifact@v3
@@ -112,3 +159,23 @@ jobs:
         with:
            token: ${{ secrets.GITHUB_TOKEN }}
            artifact_name: github-pages
+
+
+# 1) This will trigger all GitHub Actions in GSAS-II workflows that have an
+#           on: repository_dispatch:
+#
+# 2) an authorized user (Brian, or perhaps organization) creates a
+#    personal access token.
+#       Do this by clicking on "picture (upper rt) 
+#         then "Settings" in drop-down and 
+#         then select "Developer settings" (at bottom). 
+#         Finally select "Fine-grained tokens"
+#      Personal access token settings:
+#         select owner: APS;
+#         select APS/G2;
+#         Repo permissions: contents r/w & metadata: r/o.
+# 3) Save the created token in this (G2-tut) repo. 
+#     Use repo-level settings on 2nd line from top (may be in ... menu). 
+#     Select Actions in Secrets & variables and create a repository secret. 
+#     Name assigned there must match ${{ secrets.XXX }} in workflow's
+#     curl call (N.B. "Authorization:" setting)

.github/workflows/test_builddocsite.yml renamed to .github/workflows/builddocsite.yml.old

@@ -1,25 +1,16 @@
 # create a documentation web site for GSAS-II from four sources
 #  * HTML tutorials are simply copied
 #  * markdown tutorials (in ./MDtutorials) are formatted with pandoc and are copied over
+#  * HTML help files are copied over from the GSAS-II sources
 #  * sphinx is used to generate HTML from files in ./webdocs
 
 # Also the tutorials.html file and the */data/index.html files are
 #     created by running scripts/makeGitTutorial
 
-# this is a development version that creates draft help pages from the MDhelp directory
-# For now
-#  * HTML help files are copied over from the GSAS-II sources
-# Eventually, the help files generated here need to get into the GSASII/help
-# directory
-
-name: build GSAS-II web site w/test MD Help
+name: build GSAS-II web site
 
-#on: [workflow_dispatch] 
-on: 
-  push:
-    branches:  
-      - "main"  
-  workflow_dispatch:
+on: [workflow_dispatch] 
+#on: [push, workflow_dispatch]
 
 permissions:
   contents: write
@@ -39,44 +30,8 @@ jobs:
       - name: pandoc setup
         uses: pandoc/actions/setup@v1
 
-      # MD help stuff
-      - name: install debian chrome
-        run: |
-          set -ex
-          wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
-          sudo apt install ./google-chrome-stable_current_amd64.deb
-   
-#      - name: test newly-installed chrome
-#        run: |
-#          which google-chrome-stable
-#          google-chrome-stable --version
-#          /usr/bin/google-chrome-stable --headless --disable-gpu --dump-dom https://google.com
-      - name: mkdocs setup
-        run: |
-          pip install mkdocs mkdocs-material python-markdown-math mkdocs-static-i18n
-          pip install mkdocs-to-pdf pymdown-extensions
-
       - name: Checkout
         uses: actions/checkout@v4
-
-      # MD help stuff
-      - name: convert MDhelp
-        run: |
-          cd MDhelp
-          mkdocs build
-          cp -vr site ../help_test
-          ENABLE_PDF_EXPORT=1 mkdocs build
-          mv site/GSASII-help.pdf ../docs/
-          # create an anchor index
-          python findMDanchors.py
-          cp -vr site ../help_test
-          
-      # - name: Upload help artifact  # creates zip file with website contents
-      #   uses: actions/upload-pages-artifact@v3
-      #   with:
-      #       path: MDhelp/site
-      #       name: MDhelp
-      #       retention-days: 1
 
       - name: Get tutorials index from source code
         run: |
@@ -122,7 +77,6 @@ jobs:
           sphinx-build webdocs .  # place output into root dir
           cp webdocs/_static/fix.css _static/fix.css # should be done by sphinx
 
-      # to be replaced by MD help stuff
       # get the help pages from the GSAS-II sources into the web site
       - name: Get GSAS-II
         run: |
@@ -132,7 +86,7 @@ jobs:
           mv _gsas2/GSASII/help ./help
       - name: Get rid of the rest of the GSAS-II files & other stuff not needed on web
         run: |
-          rm -rf _gsas2 webdocs scripts MDtutorials MDhelp
+          rm -rf _gsas2 webdocs scripts MDtutorials
 
       - name: Upload artifact  # creates zip file with website contents
         uses: actions/upload-pages-artifact@v3

.github/workflows/documentation.yml renamed to .github/workflows/documentation.yml.old

@@ -25,14 +25,15 @@ Help pages
 
 The GSAS-II GUI provides context-based help via web files that are
 distributed with the program, as well as can be `viewed here
-<help/index.html>`_. These help pages are not always complete,
-but do provide information on how different sections of the program
-work. The help information can also be viewed `as a PDF document
+<help/index.html>`_. These help pages are not complete for all
+sections of the code,
+but do provide at least some information on how every section of the program
+works. The help information can also be viewed `as a PDF document
 <https://advancedphotonsource.github.io/GSAS-II-tutorials/docs/GSASII-help.pdf>`_.
 
 Note that the help documentation was recently reformatted and updated
 as MarkDown (simple text) input files found
-`here in GitHub<https://github.com/AdvancedPhotonSource/GSAS-II-tutorials/tree/main/MDhelp>`_.
+`in GitHub, here<https://github.com/AdvancedPhotonSource/GSAS-II-tutorials/tree/main/MDhelp>`_.
 Comments, corrections, additions and issue reports on Help are most welcome. 
 
 .. index:: Source code documentation