builddocsite.yml

# create a documentation web site for GSAS-II from four sources
#  1. HTML tutorials are simply copied
#  2. markdown tutorials (in ./MDtutorials) are formatted with pandoc and are copied over
#     * the tutorials.html file and the */data/index.html files are
#        created by running scripts/makeGitTutorial.py
#  3. sphinx is used to generate HTML from files in ./webdocs
#  4. the help pages are created from the .md file in the MDhelp directory

name: build GSAS-II web site w/MD Help

#on: [workflow_dispatch] 
on: 
  push:
    branches:  
      - "main"  
  workflow_dispatch:

permissions:
  contents: write
  id-token: write
  pages: write

jobs:
  build:       # Build web pages
    runs-on: ubuntu-latest
    steps:
      - name: Python setup
        uses: actions/setup-python@v3
      - name: Sphinx setup
        run: |
          pip install sphinx sphinx_readable_theme
      - 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/main/GSASII/tutorialIndex.py -o scripts/tutorialIndex.py

      - name: convert MarkDown tutorials
        run: |
          cd MDtutorials
          for path in ./*; do
            [ -d "${path}" ] || continue # skip if not a directory
            dirname="$(basename "${path}")"
            dest="../${dirname}"
            mkdir -pv ${dest}
            [ ! -d "${path}/data" ] || cp -r "${path}/data" ${dest}/
            [ ! -d "${path}/imgs" ] || cp -r "${path}/imgs" ${dest}/
            cp tutorial.css ${dest}
            for fil in $dirname/*.md; do
              outfile="${dest}/$(basename "${fil%.md}.html")"
              echo "creating $outfile from $fil"
              pandoc --standalone --mathjax --css tutorial.css -o ${outfile} ${fil}
              sed -i "s/<figure>/<BR clear=all><figure>/g" ${outfile}
            done
            #git add ${dest}
          done
          mkdir ../tutorial_template
          cp tutorial.css ../tutorial_template
          fil=template.md
          outfile=../tutorial_template/template.html
          echo "creating $outfile from $fil"
          pandoc --standalone --mathjax --css tutorial.css -o ${outfile} ${fil}
          sed -i "s/<figure>/<BR clear=all><figure>/g" ${outfile}
          mkdir ../tutorial_template/imgs
          cp FontSize/imgs/*.png ../tutorial_template/imgs/
          #cd ..

      - name: build tutorials index 
        run: |
          cd scripts
          python makeGitTutorial.py ..

      - 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 rid of the rest of the GSAS-II files & other stuff not needed on web
        run: |
          rm -rf webdocs scripts MDtutorials MDhelp Outtakes
        
      - name: Upload artifact  # creates zip file with website contents
        uses: actions/upload-pages-artifact@v3
        with:
            path: .
            name: github-pages
            retention-days: 1

  deploy:   # Deployment of web pages to GitHub pages
    needs: build     
    permissions:
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4
        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)