Skip to content
Docs

Fix manual and turn on documentation build for new Pull Requests #1604

Sign in to view logs

Fix manual and turn on documentation build for new Pull Requests

Fix manual and turn on documentation build for new Pull Requests #1604

Workflow file for this run

.github/workflows/docs.yml at 61d15cb
# manuals -> master latest e LTS
# dev/<branch>/arch
#
# link a pdf e constraint coi test ok
# Tree Structure
# --------------
#
# oq-engine
# <x.y>|master
# PDF
# <pdf_docs>
# reference
# manual
# advanced
# latest -> <latest x.y>
# LTS -> <LTS x.y>
# reference
# latest -> ../latest/reference
# LTS -> ../LTS/reference
# master -> ../master/reference
# manual
# latest -> ../latest/manual
# LTS -> ../LTS/manual
# master -> ../master/manual
# advanced
# latest -> ../latest/advanced
# LTS -> ../LTS/advanced
# master -> ../master/advanced
# manuals
# OpenQuake Manual <x.y>.pdf -> ../oq-engine/<x.y>/PDF/OpenQuake Manual <x.y>.pdf
# OpenQuake Manual latest.pdf -> OpenQuake Manual <latest_(x.y)>.pdf
# OpenQuake Manual LTS.pdf -> OpenQuake Manual <LTS_(x.y)>.pdf
#
# .dev
# oq-engine
# <branch>
# PDF
# <pdf_docs>
# reference
# manual
# advanced
# manuals
# OpenQuake Manual <branch>.pdf -> ../oq-engine/<branch>/PDF/OpenQuake Manual <branch>.pdf
#
---
name: Docs
on:
workflow_dispatch:
inputs:
oq-release:
description: 'OQ Release'
required: true
default: 'dev'
type: choice
options:
- dev
- master
- release
- LTS
push:
branches: [master, 'engine-*', moster, 'ongine-*']
pull_request:
jobs:
docs:
runs-on: ubuntu-latest
env:
EV_NAME: ${{ github.event_name }}
# during devel was DOCS_BASE: ".oq-engine-docs-refact/"
DOCS_BASE: ""
GITHUB_REF: ${{ github.ref }}
GITHUB_HD_REF: ${{ github.head_ref }}
GITHUB_BS_REF: ${{ github.base_ref }}
steps:
- name: run if workflow_dispatch
if: github.event_name == 'workflow_dispatch'
shell: bash
run: echo "Action triggered by 'workflow_dispatch' ($EV_NAME)"
- name: run if push
if: github.event_name == 'push'
shell: bash
run: echo "Action triggered by 'push' ($EV_NAME)"
- name: identify github reference
run: |
echo "DOCS_BASE: [$DOCS_BASE]"
echo "REF: $GITHUB_REF"
echo "REF_NAME: $GITHUB_REF_NAME"
echo "HD_REF: $GITHUB_HD_REF"
echo "BS_REF: $GITHUB_BS_REF"
- name: Check out the codebase
uses: actions/checkout@v2
- name: Set up Python 3.8
uses: actions/setup-python@v2
with:
python-version: '3.8'
- name: Upgrade pip and install requirements
run: |
pip install -U pip
pip install -r ./requirements-py38-linux64.txt
pip install sphinx==6.2 pydata-sphinx-theme
pip install --upgrade myst-parser
- name: Install oq engine
run: |
pip install -e .[dev]
python3 -c "import openquake.baselib as m; print(m.__version__.rpartition('.')[0])"
- name: Make docs and rsync to docs.openquake.org
shell: bash
env:
# Used
BUILD: ${{ github.event.inputs.oq-release }}
DOCS_SSH: ${{ secrets.DOCS_ARTIFACTS }}
# GITHUB_PULL_REQUEST: ${{ github.event.number }}
GITHUB_DEF_BR: ${{ github.event.repository.default_branch }}
GITHUB_REF: ${{ github.ref }}
GITHUB_HD_REF: ${{ github.head_ref }}
GITHUB_BS_REF: ${{ github.base_ref }}
UPLOAD: ${{ github.event.inputs.git-ref }}
# JUST TO TEST MULTI_DOCS
MULTI_DOCS_FOR_DEVEL: "true"
run: |
bash --version
LTS_VER=$(grep '^Current LTS' README.md | sed 's/.*OpenQuake Engine //g;s/\*\*.*//g')
ENG_VER=$(python3 -c "import openquake.baselib as m; print(m.__version__.rpartition('.')[0])")
if [ -z "$BUILD" ]; then
if [[ "$GITHUB_REF_NAME" == "master" || "$GITHUB_REF_NAME" == "moster" ]]; then
BUILD=master
elif [[ "$GITHUB_REF_NAME" =~ ^engine- || "$GITHUB_REF_NAME" =~ ^ongine- ]]; then
BRANCH_VER="${GITHUB_REF_NAME#engine-}"
if [ "$BRANCH_VER" == "$GITHUB_REF_NAME" ]; then
BRANCH_VER="${GITHUB_REF_NAME#ongine-}"
fi
# TEST: ENABLE IF NEEDED
# ENG_VER=$BRANCH_VER
if [ "$BRANCH_VER" != "$ENG_VER" ]; then
echo "Versions don't match (BRANCH_VER: [$BRANCH_VER] ENG_VER: [$ENG_VER])"
exit 2
fi
if [[ "$BRANCH_VER" == "$LTS_VER" ]]; then
BUILD=LTS
else
BUILD=release
fi
else
BUILD=dev
fi
fi
REL_VERS="$(git ls-remote --heads | grep -v '^From' | grep '/engine-' | sed 's/^.*ngine-//g' | sort -t. -k 1,1n -k 2,2n -k 3,3n -k 4,4n)"
LATEST_VER="$(echo "$REL_VERS" | tail -n 1)"
ALL_VERS="$((git ls-remote --heads | grep -v '^From' | grep '/engine-' | sed 's/^.*ngine-//g' ; echo "$ENG_VER") | sort -t. -k 1,1n -k 2,2n -k 3,3n -k 4,4n | uniq)"
PDFDOCS="manuals/"
TARGET_LINK=""
PDF_VER_LINK=""
if [ "$BUILD" == "release" -o "$BUILD" == "LTS" ]; then
TARGET="oq-engine/$ENG_VER/"
# TARGET_LINK="${DOCS_BASE}oq-engine/$BUILD"
PDF_VER="${ENG_VER}"
if [ "$BUILD" == "release" ]; then
if [ "$ENG_VER" == "$LATEST_VER" ]; then
PDF_VER_LINK="latest"
fi
elif [ "$BUILD" == "LTS" ]; then
PDF_VER_LINK="LTS"
fi
elif [ "$BUILD" == "master" ]; then
TARGET="oq-engine/master/"
PDF_VER="(master)"
elif [ "$BUILD" == "dev" ]; then
DOCS_BASE="${DOCS_BASE}.dev/"
if echo "$GITHUB_REF_NAME" | grep -q '[0-9]\+/merge'; then
TARGET="oq-engine/$GITHUB_HD_REF/"
PDF_VER="($GITHUB_HD_REF)"
else
TARGET="oq-engine/$GITHUB_REF_NAME/"
PDF_VER="($GITHUB_REF_NAME)"
fi
PDFDOCS="manuals/"
else
echo "BUILD [$BUILD] not recognized"
exit 3
fi
PDFDEST=${PDFDOCS}
# TEST PER PDF_VER_LINK
# PDF_VER_LINK=test_ver_link
echo "LATEST_VER: [$LATEST_VER]"
echo "BUILD: [$BUILD]"
echo "LTS_VER: [$LTS_VER]"
echo "ENG_VER: [$ENG_VER]"
echo "TARGET: [$TARGET]"
echo "TARGET_LINK: [$TARGET_LINK]"
echo "PDF_VER: [$PDF_VER]"
echo "PDF_VER_LINK: [$PDF_VER_LINK]"
echo "PDFDOCS [$PDFDOCS]"
echo "PDFDEST [$PDFDEST]"
echo "----"
echo "GITHUB_PULL_REQUEST: [$GITHUB_PULL_REQUEST]"
echo "GITHUB_DEF_BR: [$GITHUB_DEF_BR]"
echo "GITHUB_REF: [$GITHUB_REF]"
echo "GITHUB_HD_REF: [$GITHUB_HD_REF]"
echo "GITHUB_BS_REF: [$GITHUB_BS_REF]"
echo "UPLOAD: [$UPLOAD]"
# multi-version doc switcher could be runned just from master because
# is the only one known the master version (from sources)
set -x
if [ "$MULTI_DOCS_FOR_DEVEL" == "true" -o "$BUILD" == "master" ]; then
ddown_adv="["
ddown_man="["
for v in $ALL_VERS; do
ver_maj="$(echo "$v" | sed 's/\([0-9]\+\)\..*/\1/g')"
ver_min="$(echo "$v" | sed 's/[0-9]\+\.\(.*\)$/\1/g')"
pfx=""
sfx=""
if [ "$v" = "$ENG_VER" ]; then
pfx="development"
master_rename="true"
else
master_rename="false"
fi
# if [ "$v" = "$LATEST_VER" ]; then
# if [ "$sfx" ]; then
# sfx="${sfx}, latest"
# else
# sfx="latest"
# fi
# fi
if [ "$v" = "$LTS_VER" ]; then
if [ "$sfx" ]; then
sfx="${sfx}, LTS"
else
sfx="LTS"
fi
fi
if [ "$sfx" ]; then
sfx=" (${sfx})"
fi
# policies for the user manual version switcher menu
if ( (( "$ver_maj" == 3 )) && (( "$ver_min" >= 16 )) ) || (( "$ver_maj" > 3 )); then
if [ "$master_rename" == "true" ]; then
ver_name="${pfx}"
ver_val="master"
else
ver_name="${ver_maj}.${ver_min}${sfx}"
ver_val="${ver_maj}.${ver_min}"
fi
ver_url="https://docs.openquake.org/${DOCS_BASE}oq-engine/${ver_val}/manual/"
if [ "$ddown_man" != "[" ]; then
ddown_man="${ddown_man}, "
fi
ddown_man="${ddown_man}{ \"name\": \"${ver_name}\", \"version\": \"$ver_val\", \"url\": \"${ver_url}\" }"
fi
# policies for the advanced manual version switcher menu
if ( (( "$ver_maj" == 3 )) && (( "$ver_min" >= 16 )) ) || (( "$ver_maj" > 3 )); then
if [ "$master_rename" == "true" ]; then
ver_name="${pfx}"
ver_val="master"
else
ver_name="${ver_maj}.${ver_min}${sfx}"
ver_val="${ver_maj}.${ver_min}"
fi
ver_url="https://docs.openquake.org/${DOCS_BASE}oq-engine/${ver_val}/advanced/"
if [ "$ddown_adv" != "[" ]; then
ddown_adv="${ddown_adv}, "
fi
ddown_adv="${ddown_adv}{ \"name\": \"${ver_name}\", \"version\": \"$ver_val\", \"url\": \"${ver_url}\" }"
fi
done
ddown_man="${ddown_man}]"
echo "$ddown_man" > dot_ddown_man.json
ddown_adv="${ddown_adv}]"
echo "$ddown_adv" > dot_ddown_adv.json
fi
set +x
gpg --quiet --batch --yes --decrypt --passphrase="$DOCS_SSH" --output ./.deploy_rsa ./.deploy_docs.enc
chmod 600 ./.deploy_rsa
eval $(ssh-agent -s) && ssh-add ./.deploy_rsa
if [ -f "dot_ddown_man.json" ]; then
rsync -s -e 'ssh -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null' --rsync-path="mkdir -p \"${DOCS_BASE}oq-engine\" && rsync" dot_ddown_man.json "docs@docs.openquake.org:${DOCS_BASE}oq-engine/.ddown_man.json"
fi
if [ -f "dot_ddown_adv.json" ]; then
rsync -s -e 'ssh -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null' --rsync-path="mkdir -p \"${DOCS_BASE}oq-engine\" && rsync" dot_ddown_adv.json "docs@docs.openquake.org:${DOCS_BASE}oq-engine/.ddown_adv.json"
fi
sudo apt update; sudo apt-get install -y texlive-fonts-recommended texlive-latex-extra latexmk gpg
echo "Make OpenQuake Manual (HTML and PDF)"
cd doc/manual && make html && make latexpdf
echo "Uploading OpenQuake Manual (PDF)"
rsync -s -e 'ssh -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null' -ax --rsync-path="mkdir -p \"${DOCS_BASE}${TARGET}PDF\" && rsync" build/latex/OpenQuakeEngineManual.pdf "docs@docs.openquake.org:${DOCS_BASE}${TARGET}PDF/OpenQuake Manual ${PDF_VER}.pdf"
ssh -v -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null docs@docs.openquake.org "bash -cx 'cd \"${DOCS_BASE}${PDFDOCS}\"; ln -sf \"../${TARGET}PDF/OpenQuake Manual ${PDF_VER}.pdf\" .'"
if [ "$PDF_VER_LINK" ]; then
echo "Found PDF_VER_LINK set [$PDF_VER_LINK]"
ssh -v -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null docs@docs.openquake.org "bash -cx 'cd \"${DOCS_BASE}manuals/\"; ln -sf \"OpenQuake Manual ${PDF_VER}.pdf\" \"OpenQuake Manual (${PDF_VER_LINK}).pdf\"'"
fi
echo "Uploading OpenQuake Manual (HTML)"
rsync -s -e 'ssh -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null' -ax --delete build/html/ "docs@docs.openquake.org:/var/www/docs.openquake.org/${DOCS_BASE}${TARGET}manual/"
echo "------"
echo "Make Reference Manual (HTML)"
cd ../sphinx && make html
echo "Upload Reference Manual (HTML)"
rsync -s -e 'ssh -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null' -ax --delete build/html/ "docs@docs.openquake.org:${DOCS_BASE}${TARGET}reference/"
echo "------"
echo "Make Advanced Manual (PDF)"
cd ../adv-manual
sed -i "s@#PDF_VER#@${PDF_VER}@g;s@#TARGET#@${DOCS_BASE}${TARGET}@g" index.rst
make clean && make latexpdf
echo "Upload OpenQuakeforAdvancedUsers (PDF)"
rsync -e 'ssh -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null' -ax --delete build/latex/OpenQuakeforAdvancedUsers.pdf "docs@docs.openquake.org:${DOCS_BASE}${TARGET}PDF/"
ssh -v -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null docs@docs.openquake.org "bash -cx 'cd \"${DOCS_BASE}${PDFDOCS}\"; ln -sf \"../${TARGET}PDF/OpenQuakeforAdvancedUsers.pdf\" \"OpenQuake for Advanced Users ${PDF_VER}.pdf\"'"
echo "Make Advanced Manual (HTML)"
cd ../adv-manual && make clean && make html
echo "Upload OpenQuakeforAdvancedUsers (HTML)"
rsync -e 'ssh -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null' -ax --delete build/html/ "docs@docs.openquake.org:${DOCS_BASE}${TARGET}advanced/"
if [ "$BUILD" == "LTS" ]; then
ssh -v -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null docs@docs.openquake.org "bash -cx 'cd \"${DOCS_BASE}oq-engine/\"; ln -snf \"$ENG_VER\" LTS'"
fi
if [ "$BUILD" == "release" -o "$BUILD" == "LTS" ]; then
if [ "$LATEST_VER" == "$ENG_VER" ]; then
ssh -v -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null docs@docs.openquake.org "bash -cx 'cd \"${DOCS_BASE}oq-engine/\"; ln -snf \"$ENG_VER\" latest'"
fi
fi