buildDocs.sh (4716B)
1 #!/bin/bash 2 set -x 3 ################################################################################ 4 # File: buildDocs.sh 5 # Purpose: Script that builds our documentation using sphinx and updates GitHub 6 # Pages. This script is executed by: 7 # .github/workflows/docs_pages_workflow.yml 8 # 9 # Authors: Michael Altfield <michael@michaelaltfield.net> 10 # Created: 2020-07-17 11 # Updated: 2020-07-23 12 # Version: 0.2 13 ################################################################################ 14 15 ################### 16 # INSTALL DEPENDS # 17 ################### 18 19 apt-get update 20 apt-get -y install git rsync pandoc python3-sphinx python3-sphinx-rtd-theme python3-stemmer python3-git python3-pip python3-venv python3-virtualenv python3-setuptools 21 22 python3_venv_dir=`mktemp -d` 23 24 python3 -m venv "$python3_venv_dir" 25 26 "${python3_venv_dir}/bin/python" -m pip install --upgrade rinohtype pygments sphinx sphinx-rtd-theme sphinx-tabs stemmer GitPython docutils==0.16 pandoc 27 "${python3_venv_dir}/bin/python" -m pip list 28 29 # get rid of all these safe dir warnings 30 git config --global --add safe.directory '*' 31 32 ##################### 33 # DECLARE VARIABLES # 34 ##################### 35 36 pwd 37 ls -lah 38 export SOURCE_DATE_EPOCH=$(git log -1 --pretty=%ct) 39 40 # make a new temp dir which will be our GitHub Pages docroot 41 docroot=`mktemp -d` 42 43 export REPO_NAME="${GITHUB_REPOSITORY##*/}" 44 45 ############## 46 # BUILD DOCS # 47 ############## 48 49 export SPHINXBUILD="${python3_venv_dir}/bin/sphinx-build" 50 51 # first, cleanup any old builds' static assets 52 make -C docs clean 53 54 # get a list of branches, excluding 'HEAD' and 'gh-pages' 55 versions="`git for-each-ref '--format=%(refname:lstrip=-1)' refs/remotes/origin/ | grep -viE '^(HEAD|gh-pages)$'`" 56 ls 57 for current_version in ${versions}; do 58 59 # make the current language available to conf.py 60 export current_version 61 git checkout ${current_version} 62 63 echo "INFO: Building sites for ${current_version}" 64 65 cd docs && "${python3_venv_dir}/bin/python" mm-converter.py 66 cd .. 67 68 # skip this branch if it doesn't have our docs dir & sphinx config 69 if [ ! -e 'docs/conf.py' ]; then 70 echo -e "\tINFO: Couldn't find 'docs/conf.py' (skipped)" 71 continue 72 fi 73 74 languages="en" 75 for current_language in ${languages}; do 76 77 # make the current language available to conf.py 78 export current_language 79 80 ########## 81 # BUILDS # 82 ########## 83 echo "INFO: Building for ${current_language}" 84 85 # HTML # 86 "$SPHINXBUILD" -b html docs/ docs/_build/html/${current_language}/${current_version} -D language="${current_language}" 87 88 # copy the static assets produced by the above build into our docroot 89 rsync -av "docs/_build/html/" "${docroot}/" 90 91 done 92 93 done 94 95 # return to master branch 96 git checkout master 97 98 ####################### 99 # Update GitHub Pages # 100 ####################### 101 102 git config --global user.name "${GITHUB_ACTOR}" 103 git config --global user.email "${GITHUB_ACTOR}@users.noreply.github.com" 104 105 pushd "${docroot}" 106 107 # don't bother maintaining history; just generate fresh 108 git init 109 git remote add deploy "https://token:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git" 110 git checkout -b gh-pages 111 112 # add .nojekyll to the root so that github won't 404 on content added to dirs 113 # that start with an underscore (_), such as our "_content" dir.. 114 touch .nojekyll 115 116 # add redirect from the docroot to our default docs language/version 117 cat > index.html <<EOF 118 <!DOCTYPE html> 119 <html> 120 <head> 121 <title>${REPO_NAME} Docs</title> 122 <meta http-equiv = "refresh" content="0; url='/${REPO_NAME}/en/master/'" /> 123 </head> 124 <body> 125 <p>Please wait while you're redirected to our <a href="/${REPO_NAME}/en/master/">documentation</a>.</p> 126 </body> 127 </html> 128 EOF 129 130 # Add README 131 cat > README.md <<EOF 132 # GitHub Pages Cache 133 134 Nothing to see here. The contents of this branch are essentially a cache that's not intended to be viewed on github.com. 135 136 137 If you're looking to update documentation, check the relevant development branch's 'docs/' dir. 138 139 For more information on how this documentation is built using Sphinx, Read the Docs, and GitHub Actions/Pages, see: 140 141 * https://tech.michaelaltfield.net/2020/07/18/sphinx-rtd-github-pages-1 142 EOF 143 144 # copy the resulting html pages built from sphinx above to our new git repo 145 git add . 146 147 # commit all the new files 148 msg="Updating Docs for commit ${GITHUB_SHA} made on `date -d"@${SOURCE_DATE_EPOCH}" --iso-8601=seconds` from ${GITHUB_REF} by ${GITHUB_ACTOR}" 149 git commit -am "${msg}" 150 151 # overwrite the contents of the gh-pages branch on our github.com repo 152 git push deploy gh-pages --force 153 154 popd # return to main repo sandbox root 155 156 # exit cleanly 157 exit 0