Skip to content

Improve diagnostics & reporting of lineup2() plan #351

Improve diagnostics & reporting of lineup2() plan

Improve diagnostics & reporting of lineup2() plan #351

Workflow file for this run

name: Publish Sphinx Docs to GitHub Pages
on:
# Build the docs on pushes to main branch, PRs to main branch, and new tags.
# Publish only on demand.
push:
branches:
- main
tags:
- "*" # all tags
pull_request:
branches:
- main
workflow_dispatch: # allow manual triggering
inputs:
deploy:
description: "Deploy documentation"
type: boolean
required: true
default: false
defaults:
run:
shell: bash -l {0}
jobs:
docs:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
with:
fetch-depth: 0 # otherwise, you will get "failed to push refs to dest repo"
- name: Setup Python
uses: actions/setup-python@v5
with:
python-version: "3.11"
- name: Deploy Information
if: ${{ github.event.inputs.deploy }}
run: |
echo "The will be published from this workflow run."
- name: Install pandoc
run: |
set -vxeuo pipefail
sudo apt-get update && \
sudo apt-get -y install pandoc
- name: Install Sphinx build requirements
run: |
pip install -r docs/requirements.txt
- name: Install our package
run: |
pip install --no-deps -e .
- name: Diagnostic
run: |
echo $(which pandoc)
echo $(which sphinx-build)
- name: Make Temporary Directory for Sphinx content
run: |
echo "SRC_DIR=$(pwd)" >> ${GITHUB_ENV}
echo "TMP_DIR=$(mktemp -d)" >> ${GITHUB_ENV}
# next step also creates _version.py file
echo "VERSION=$(python -m setuptools_scm)" >> ${GITHUB_ENV}
- name: Show Environment variables
run: |
echo "SRC_DIR=${SRC_DIR}"
echo "TMP_DIR=${TMP_DIR}"
echo "VERSION=${VERSION}"
- name: Sphinx
run: |
TZ=UTC sphinx-build -M html ./docs/source "${TMP_DIR}/build"
- name: Build Info
run: ls -lAFghR "${TMP_DIR}/build/html"
- name: Upload Docs ZIP file as artifact
uses: actions/upload-artifact@v4
with:
name: apstools-docs
path: ${{ env.TMP_DIR }}/build/html
- name: Re-build the master directory (contains all documentation versions)
run: |
set -vxeuo pipefail
cp .github/index.html "${TMP_DIR}"
cd "${TMP_DIR}"
mv build/html "${VERSION}"
/bin/rm -rf build
ln -s "./${VERSION}" dev
# add previous documentation (built versions)
# update the switcher.json file before a new release
wget https://github.com/BCDA-APS/apstools/archive/refs/heads/gh-pages.zip
unzip -q gh-pages.zip
/bin/rm gh-pages.zip
source "${SRC_DIR}/.github/scripts/define_versions.sh"
for v in ${versions}
do
if [ -d "apstools-gh-pages/${v}" ]
then
echo "directory 'apstools-gh-pages/${v}' exists"
mv "apstools-gh-pages/${v}" ./
latest="${v}"
fi
done
echo "latest=${latest}"
ln -s "./${latest}" ./latest
/bin/rm -rf apstools-gh-pages
- name: Info
run: |
set -vxeuo pipefail
cd "${TMP_DIR}"
echo "pwd=$(pwd)"
ls -laFGh
du -shc *
- name: Publish (push gh-pages branch) only on demand
uses: peaceiris/actions-gh-pages@v4
if: ${{ github.event.inputs.deploy }}
with:
publish_branch: gh-pages
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ${{ env.TMP_DIR }}
force_orphan: true