gen_docs

#!/bin/bash
# SPDX-License-Identifier: Apache-2.0
# Copyright (C) 2020-2022 OKTET Labs Ltd. All rights reserved.
#
# doxygen filter can expect the following environment variables are set:
# - DOWNLOAD_DOC_LINK - path to TAR.GZ packed documentation file.
#                       If this variable is set, then "Download"
#                       section will be added to the documentation mainpage.
# - DOXYREST_PREFIX   - prefix path to doxyrest if you want to use sphinx to
#                       generate HTML
#

[ -z $TE_BASE ] && export TE_BASE="$(cd "$(dirname "$(which "$0")")"; pwd -P)"

help() {
    cat <<EOF
This is a wrapper script which builds the autogenerated part of the
Test Environment documentation.

Usage:
  $ gen_docs [-s|--sphinx-only] [-e|--exclude-global] [-h|--help]

  -s, --sphinx-only       - Do not run doxygen and doxyrest,
                            generate only html documentation based on rst pages
                            in doc/sphinx
  -e, --exclude-global    - Do not generate global namespace
  -c, --check-only        - Run only doxygen, no doxyrest and sphinx, produce
                            no output but list all warnings
  -h, --help              - Print this help and exit

Documentation will be located at doc/generated/html/
EOF
}

DO_EXCLUDE_GLOBAL=false
SPHINX_ONLY=false
while [ $# -gt 0 ]; do
    case "$1" in
        -h|--help)
            help
            exit 0
            ;;
        -e|--exclude-global)
            DO_EXCLUDE_GLOBAL=true
            ;;
        -s|--sphinx-only)
            SPHINX_ONLY=true
            ;;
        -c|--check-only)
            CHECK_ONLY=true
            ;;
        *)
            echo "Unknown option '$1'">&2
            help
            exit 1
            ;;
    esac

    shift
done

# Go through conf.py, collect patterns from "exclude_patterns",
# add them and 'generated/global.rst' to the list of patterns to be excluded
function exclude_global()
{
    local IN_EXCL=0
    local GLOBALRST="generated/global.rst"
    local EXCLUDE_PATTERNS_START_STRING="exclude_patterns = ["
    local EXCLUDE_PATTERNS_END_STRING="]"
    local EXCLUDE_PATTERNS=

    while read line; do
        if [ $IN_EXCL -eq 1 -a "$line" = "$EXCLUDE_PATTERNS_END_STRING" ]; then
            IN_EXCL=0
        fi

        if [ $IN_EXCL -eq 1 ]; then
            if [ "$line" = "'$GLOBALRST'" -o "$line" = "'$GLOBALRST'," ]; then
                return
            fi
            EXCLUDE_PATTERNS+=`echo $line | sed "s/'//g"`
        fi

        if [ "$line" = "$EXCLUDE_PATTERNS_START_STRING" ]; then
            IN_EXCL=1
        fi
    done < doc/sphinx/conf.py

    if [ "${EXCLUDE_PATTERNS:(-1)}" = "," ]; then
        EXCLUDE_PATTERNS=`echo "$EXCLUDE_PATTERNS" | sed 's/.$//'`
    fi

    if [ -z "$EXCLUDE_PATTERNS" -o "${EXCLUDE_PATTERNS:(-1)}" = "," ]; then
        EXCLUDE_PATTERNS+="$GLOBALRST"
    else
        EXCLUDE_PATTERNS+=",$GLOBALRST"
    fi

    # Override exclude_patterns from conf.py
    SPHINX_EXCLUDE_PATTERNS=(-D exclude_patterns=${EXCLUDE_PATTERNS})
}

function check_sphinx_binary()
{
    rm -rf doc/generated/html

    [ -z "$SPHINX_BUILD_BIN" ] && SPHINX_BUILD_BIN="sphinx-build"
    if ! which $SPHINX_BUILD_BIN >/dev/null; then
        echo "Please install sphinx before:"
        echo " # apt-get install python-sphinx"
        echo " # apt-get install python-sphinx-rtd-theme"
        echo "If they are unavailable, try"
        echo " $ pip install sphinx"
        exit -2
    fi
}

function doxygen_check_only()
{
    # Doxygen warnings are a bit messy,
    # because warnings related to the same file
    # may not come together, and there may be
    # multiple copies of the same message.
    # The pipeline below fixes that.
    { cat Doxyfile ;
      echo "GENERATE_XML=YES" ;
      echo "GENERATE_HTML=NO";
      echo "WARN_LOGFILE=";
      echo "QUIET=YES";
    } | doxygen - 2>&1 |
        awk '/^ / {
               if (in_list)
                  buffer = buffer ","
               buffer = buffer $0;
               in_list = 1;
               next
            }
            {
               if (buffer) print buffer;
               buffer = $0;
               in_list = 0;
            }
            END { print buffer }' |
        sort -u
    exit 0
}

function generate_sphinx_only()
{
    $SPHINX_ONLY && check_sphinx_binary
    $DO_EXCLUDE_GLOBAL && exclude_global
    SPHINX_BUILD_OPTS=(
      "${SPHINX_EXCLUDE_PATTERNS[@]}"
      -j auto             # use cpu count
      -q                  # be quite: warn and error only
      doc/sphinx          # input
      doc/generated/html  # output
    )

    ${SPHINX_BUILD_BIN} "${SPHINX_BUILD_OPTS[@]}"
}

function generate_sphinx_doc()
{
    if [ -z "$DOXYREST_PREFIX" ]; then
        $TE_BASE/scripts/doxyrest_deploy.sh --how
        exit -1
    fi
    [ -z "$DOXYREST_BIN" ] && DOXYREST_BIN="$DOXYREST_PREFIX/bin/doxyrest"
    check_sphinx_binary

    ( cat Doxyfile ;
      echo "GENERATE_XML=YES" ;
      echo "GENERATE_HTML=NO" ) | doxygen - > /dev/null

    DOXYREST_OPTS=(
      --config=doc/doxyrest-config.lua
      --frame-dir=$DOXYREST_PREFIX/share/doxyrest/frame/cfamily
      --frame-dir=$DOXYREST_PREFIX/share/doxyrest/frame/common
    )

    ${DOXYREST_BIN} "${DOXYREST_OPTS[@]}" > /dev/null || exit 1

    [ -z "$SCRIPT_DIR" ] && SCRIPT_DIR="${TE_BASE}/scripts/docs"

    ${SCRIPT_DIR}/add_orphan_tag.sh || echo "Failed to add orphan tag" 1>&2

    generate_sphinx_only
}

[[ -n "$CHECK_ONLY" ]] && doxygen_check_only

$SPHINX_ONLY && generate_sphinx_only || generate_sphinx_doc

echo "" >&2
echo "###########################################" >&2
echo "## See doc/generated/html/index.html ######" >&2
echo "###########################################" >&2