publish.sh

Go to the documentation of this file.

#!/usr/bin/env bash
#
# Ran without arguments, will publish the current Doxygen output.
#
#
# Changes
# --------
#
# 20220301 (petrillo@slac.stanford.edu) [v1.2]
#   * added `--overwrite` option and reworked the internals of the update mode
#   * added `--force` option (affects only `--overwrite` so far)
#   * added current directory as priority source for the location of  Doxyfile
# 20200520 (petrillo@slac.stanford.edu) [v1.1]
#   * added script argument parsing
#   * added `--update` option
#   * the option to remove the existing data (`CleanOutputArea`) is not enabled
#


# -- BEGIN -- boilerplate settings and library loading -------------------------
SCRIPTNAME="$(basename "$0")"
SCRIPTDIR="$(dirname "$0")"

declare LibraryToLoad
for LibraryToLoad in 'settings.sh' 'utilities.sh' ; do
  
  source "${SCRIPTDIR%/}/${LibraryToLoad}" || exit $?
  
done
unset LibraryToLoad
# -- END -- boilerplate settings and library loading ---------------------------

# ------------------------------------------------------------------------------
SCRIPTVERSION="1.2"


declare -r RepoDir="./"

declare -r UpdateMode='update'
declare -r OverwriteMode='overwrite'
declare -r CleanPublishMode='newonly'


# ------------------------------------------------------------------------------
function printHelp() {
  
  cat <<EOH

Copies the documentation into the public web page storage area.

Usage:  ${SCRIPTNAME}  [options]

Supported options:
--srcdocdir=SOURCEDIR [autodetect]
    directory where the HTML documentation has been rendered
--experiment=EXPERIMENTNAME [autodetect]
    the name of the experiment (e.g. 'MicroBooNE')
--codeversion=VERSION [from metadata]
    the version of the code being documented
--update
    if there is already documentation for the same version, update it
    instead of refusing to proceed; the existing directory is not removed
    before publishing
--overwrite
    destination directory is fully removed before the copy proceeds
--force
    in options like \`--overwrite\` it does not ask for confirmation
--version , -V
    prints the script version and exits (hint: it's version ${SCRIPTVERSION}
--help , -h , -?
    prints this usage message and exits

EOH

} # printHelp()


function printVersion() {
  echo "${SCRIPTNAME} version ${SCRIPTVERSION}."
} # printVersion()


################################################################################
###  Start here!
################################################################################
#
# parameter parsing
#
declare -i NoMoreOptions
declare -i DoVersion=0 DoHelp=0
declare PublishMode="$CleanPublishMode"
declare ExitWithCode
declare Param
for (( iParam = 1 ; iParam <= $# ; ++iParam )); do
  Param="${!iParam}"
  if isFlagUnset NoMoreOptions && [[ "${Param:0:1}" == '-' ]]; then
    case "$Param" in
      ( '--experiment='* )         ExperimentName="${Param#--*=}" ;;
      ( '--srcdocdir='* )          SourceDir="${Param#--*=}" ;;
      ( '--codeversion='* )        Version="${Param#--*=}" ;;
      ( '--update' )               PublishMode="$UpdateMode" ;;
      ( '--overwrite' )            PublishMode="$OverwriteMode" ;;
      ( '--force' )                FORCE=1 ;;
      ( '--version' | '-V' )       DoVersion=1 ;;
      ( '--help' | '-h' | '-?' )   DoHelp=1 ;;
      ( '-' | '--' )               NoMoreOptions=1 ;;
      ( * )
        ERROR "Unknown option: '${Param}'."
        ExitWithCode=1
    esac
  else
    PositionalArguments+=( "$Param" )
  fi
done

[[ "${#PositionalArguments[@]}" -gt 0 ]] && FATAL 1 "Found ${#PositionalArguments[@]} spurious arguments on command line: ${PositionalArguments[@]}."

: ${ExperimentName="$(FindExperiment)"}
LASTFATAL "Can't detect the experiment name."

: ${ExperimentCodeName:="$(ExperimentCodeProduct "$ExperimentName")"}
LASTFATAL "Can't put together the experiment code repository name for '${ExperimentName}'."

if isFlagSet DoVersion ; then
  printVersion
  [[ -z "$ExitWithCode" ]] && ExitWithCode=0
fi
if isFlagSet DoHelp ; then
  printHelp
  [[ -z "$ExitWithCode" ]] && ExitWithCode=0
fi

[[ -n "$ExitWithCode" ]] && exit "$ExitWithCode"


# ------------------------------------------------------------------------------
#
# find the GIT repository (may contain doxygen file!)
#
declare GitRepoPath
GitRepoPath="$(FindGitRepository "$ExperimentCodeName")"
if [[ $? == 0 ]] && [[ -n "$GitRepoPath" ]]; then
  echo "GIT repository: '${GitRepoPath}'"
else
  echo "GIT repository not found."
  GitRepoPath=""
fi

#
# find the Doxygen configuration file
#
declare Doxyfile
Doxyfile="$(FindDoxyfile "$ExperimentName" "$(pwd)")"
if [[ $? == 0 ]] && [[ -n "$Doxyfile" ]]; then
  echo "Doxygen configuration: '${Doxyfile}'"
else
  echo "Doxygen configuration file not found."
  Doxyfile=""
fi

#
# finally find the directory of Doxygen output (hint: it's "html")
#
if [[ -z "$SourceDir" ]]; then
  [[ -r "$Doxyfile" ]] || FATAL 1 "The source directory must be specified."
  SourceDir="$(ExtractValueFromDoxyfile 'HTML_OUTPUT' "$Doxyfile")"
  [[ -n "$SourceDir" ]] || FATAL 1 "Can't extract the output directory from the Doxygen configuration file."
  echo "Doxygen output directory detected: '${SourceDir}'."
  MetadataFile="${SourceDir%/}/${MetadataFileRelPath}"
  if [[ -r "$MetadataFile" ]]; then
    MetadataVersion="$(ExtractFromMetadata 'MetadataVersion' "$MetadataFile")"
    echo "  => metadata (version ${MetadataVersion}) found at: '${MetadataFile}'"
  fi
fi
[[ -d "$SourceDir" ]] || FATAL 2 "Can't find the source directory '${SourceDir}'."

#
# with metadata we know everything about generation of documentation
#
if [[ "${MetadataVersion:-0}" -ge 1 ]]; then
  Version="$(ExtractFromMetadata 'CodeVersion' "$MetadataFile")"
  [[ $? == 0 ]] && [[ -n "$Version" ]] && echo "Code version from metadata: ${Version}."
fi

[[ -z "$Version" ]] && FATAL 1 "The version of the documentation must be specified."

#
# transfer the content
#
declare TransferLogFile="${LogDir:+${LogDir%/}/}transfer-${ExperimentCodeName}-${Version}.log"
declare -r DestVersionsDir="${PublishBaseDir:+${PublishBaseDir%/}/}${ExperimentCodeName}"
mkdir -p "$DestVersionsDir"
declare -r DestDir="${DestVersionsDir}/${Version}"
if [[ -d "$DestDir" ]]; then
  case "$PublishMode" in
    ( "$OverwriteMode" )
      echo "The existing content in '${DestDir}' will be removed before proceeding."
      if isFlagUnset FORCE ; then
        ConfirmOpt='-I'
        echo "Please confirm the removal of its content:"
      fi
      rm -Rf $ConfirmOpt "$DestDir"
      [[ -d "$DestDir" ]] && FATAL 1 "output directory won't be overwritten."
      ;;
    ( "$UpdateMode" )
      echo "The existing content in '${DestDir}' will be updated."
      # no action actually needed
      ;;
    ( "$CleanPublishMode" )
      FATAL 1 "Output directory '${DestDir}' already exists: remove it first!"
      ;;
    ( * )
      FATAL 1 "INTERNAL ERROR: PublishMode='${PublishMode}' not recognised."
      ;;
  esac
fi
declare -a Cmd=( rsync -av "${SourceDir%/}/" "${DestDir%/}/" ">&" "$TransferLogFile")

echo "Copying the documentation content:"
echo "${Cmd[@]}"
eval "${Cmd[@]}"
LASTFATAL "Error while copying the content from '${SourceDir}' to '${DestDir}'."

#
# update the link
#
echo "Updating latest version link:"
declare -r LatestLinkPath="${DestVersionsDir}/${LatestLinkName}"
[[ -h "$LatestLinkPath" ]] && rm "$LatestLinkPath"
ln -sfv "$(basename "$DestDir")" "$LatestLinkPath"