11# create a documentation web site for GSAS-II from four sources
22# * HTML tutorials are simply copied
33# * markdown tutorials (in ./MDtutorials) are formatted with pandoc and are copied over
4- # * HTML help files are copied over from the GSAS-II sources
54# * sphinx is used to generate HTML from files in ./webdocs
5+ # * the tutorials.html file and the */data/index.html files are
6+ # created by running scripts/makeGitTutorial
7+ # * the help pages are created from the .md file in the MDhelp directory
8+ # * this triggers a process that also creates the help files and places
9+ # the .html files into the GSAS-II sources
610
7- # Also the tutorials.html file and the */data/index.html files are
8- # created by running scripts/makeGitTutorial
11+ name : build GSAS-II web site w/MD Help
912
10- name : build GSAS-II web site
11-
12- on : [workflow_dispatch]
13- # on: [push, workflow_dispatch]
13+ # on: [workflow_dispatch]
14+ on :
15+ push :
16+ branches :
17+ - " main"
18+ workflow_dispatch :
1419
1520permissions :
1621 contents : write
2227 runs-on : ubuntu-latest
2328 steps :
2429
30+ - name : Trigger remote workflow to update help files in GSAS-II repo
31+ # see below for info on setting this up
32+ run : |
33+ # config var follows
34+ repo_owner="AdvancedPhotonSource"
35+
36+ curl -L \
37+ -X POST \
38+ -H "Accept : application/vnd.github+json" \
39+ -H "Authorization : Bearer ${{ secrets.G2TUT_2_G2_4HELP }}" \
40+ -H "X-GitHub-Api-Version : 2022-11-28" \
41+ https://api.github.com/repos/$repo_owner/GSAS-II/dispatches \
42+ -d '{"event_type" : " remote build" , "client_payload": {"service": "remote build", "unit": false, "integration": true}}'
43+
2544 - name : Python setup
2645 uses : actions/setup-python@v3
2746 - name : Sphinx setup
@@ -30,14 +49,49 @@ jobs:
3049name : pandoc setup
3150 uses : pandoc/actions/setup@v1
3251
52+ # MD help stuff
53+ - name : install debian chrome
54+ run : |
55+ set -ex
56+ wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
57+ sudo apt install ./google-chrome-stable_current_amd64.deb
58+
59+ # - name: test newly-installed chrome # for debug
60+ # run: |
61+ # which google-chrome-stable
62+ # google-chrome-stable --version
63+ # /usr/bin/google-chrome-stable --headless --disable-gpu --dump-dom https://google.com
64+ - name : mkdocs setup
65+ run : |
66+ pip install mkdocs mkdocs-material python-markdown-math mkdocs-static-i18n
67+ pip install mkdocs-to-pdf pymdown-extensions
68+
3369name : Checkout
3470 uses : actions/checkout@v4
71+
72+ # MD help stuff
73+ - name : convert MDhelp
74+ run : |
75+ cd MDhelp
76+ #mkdocs build
77+ ENABLE_PDF_EXPORT=1 mkdocs build
78+ mv site/GSASII-help.pdf ../docs/
79+ # create an anchor index in the help files (only used by Python code)
80+ python findMDanchors.py
81+ cp -vr site/* ../help/
82+
83+ # - name: Upload help artifact # creates zip file with website contents for debug
84+ # uses: actions/upload-pages-artifact@v3
85+ # with:
86+ # path: MDhelp/site
87+ # name: MDhelp
88+ # retention-days: 1
3589
3690 - name : Get tutorials index from source code
3791 run : |
3892 curl -L https://github.com/AdvancedPhotonSource/GSAS-II/raw/master/GSASII/tutorialIndex.py -o scripts/tutorialIndex.py
3993
40- name : convert tutorials
94+ name : convert MarkDown tutorials
4195 run : |
4296 cd MDtutorials
4397 for path in ./*; do
@@ -63,30 +117,23 @@ jobs:
63117 cd scripts
64118 python makeGitTutorial.py ..
65119
66- # - name: Note changed files
67- # run: |
68- # git add tutorials.html
69- # git add */data/index.html
70- # git status
71- # git commit -m"changes from automated build of tutorials"
72- # - name: Push changes
73- # uses: ad-m/github-push-action@master
74-
75120name : Sphinx build
76121 run : |
77122 sphinx-build webdocs . # place output into root dir
78123 cp webdocs/_static/fix.css _static/fix.css # should be done by sphinx
79124
125+ # to be replaced by MD help stuff
80126 # get the help pages from the GSAS-II sources into the web site
81- - name : Get GSAS-II
82- run : |
83- git clone --depth 1 https://github.com/AdvancedPhotonSource/GSAS-II.git _gsas2
84- name : move help into site
85- run : |
86- mv _gsas2/GSASII/help ./help
127+ # - name: Get GSAS-II
128+ # run: |
129+ # git clone --depth 1 https://github.com/AdvancedPhotonSource/GSAS-II.git _gsas2
130+ # - name: move help into site
131+ # run: |
132+ # mv _gsas2/GSASII/help ./help
133+
87134 - name : Get rid of the rest of the GSAS-II files & other stuff not needed on web
88135 run : |
89- rm -rf _gsas2 webdocs scripts MDtutorials
136+ rm -rf webdocs scripts MDtutorials MDhelp
90137
91138name : Upload artifact # creates zip file with website contents
92139 uses : actions/upload-pages-artifact@v3
@@ -112,3 +159,23 @@ jobs:
112159 with :
113160 token : ${{ secrets.GITHUB_TOKEN }}
114161 artifact_name : github-pages
162+
163+
164+ # 1) This will trigger all GitHub Actions in GSAS-II workflows that have an
165+ # on: repository_dispatch:
166+ #
167+ # 2) an authorized user (Brian, or perhaps organization) creates a
168+ # personal access token.
169+ # Do this by clicking on "picture (upper rt)
170+ # then "Settings" in drop-down and
171+ # then select "Developer settings" (at bottom).
172+ # Finally select "Fine-grained tokens"
173+ # Personal access token settings:
174+ # select owner: APS;
175+ # select APS/G2;
176+ # Repo permissions: contents r/w & metadata: r/o.
177+ # 3) Save the created token in this (G2-tut) repo.
178+ # Use repo-level settings on 2nd line from top (may be in ... menu).
179+ # Select Actions in Secrets & variables and create a repository secret.
180+ # Name assigned there must match ${{ secrets.XXX }} in workflow's
181+ # curl call (N.B. "Authorization:" setting)
0 commit comments