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)"

SPHINX_LOG="${TE_BASE}/doc/generated/sphinx.log"

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

    # Regenerate the option list the Dispatcher page includes.
    [[ -z "$SCRIPT_DIR" ]] && SCRIPT_DIR="${TE_BASE}/scripts/docs"
    ${SCRIPT_DIR}/gen_dispatcher_options.sh ||
        echo "Failed to generate the Dispatcher option list" 1>&2



    # The sidebar hierarchy comes from the @defgroup/@ingroup tags rather than
    # from hand-written toctrees; --xml additionally proves that every group
    # Doxygen found can actually be reached from a page.  See the script.
    local xml_opt=()
    [ -d "${TE_BASE}/doc/generated/xml" ] &&
        xml_opt=(--xml "${TE_BASE}/doc/generated/xml")
    ${SCRIPT_DIR}/gen_toctrees.py --te-base "${TE_BASE}" "${xml_opt[@]}" \
        --generated "${TE_BASE}/doc/sphinx/generated" || {
        echo "Failed to generate the navigation" 1>&2
        return 1
    }

    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 has no way to make a single warning class fatal, and the tree
    # still carries enough pre-existing cross-reference damage that -W would
    # fail on everything at once.  Gate on the navigation warnings alone: a
    # page nobody links to, or a toctree entry pointing at nothing, means the
    # sidebar has silently lost a subtree.
    ${SPHINX_BUILD_BIN} "${SPHINX_BUILD_OPTS[@]}" 2>&1 | tee "${SPHINX_LOG}"
    local status=${PIPESTATUS[0]}

    local nav
    nav="$(grep -E "isn't included in any toctree|toctree contains reference to nonexisting document" "${SPHINX_LOG}")"
    if [ -n "${nav}" ]; then
        echo "" 1>&2
        echo "Navigation is broken:" 1>&2
        echo "${nav}" 1>&2
        status=1
    fi

    return ${status}
}

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
    )

    # Doxygen 1.9 moved grouped member definitions out of the file compounds
    # that doxyrest reads them from; without this the manual comes out with no
    # API reference at all.  See the script.
    [ -z "$SCRIPT_DIR" ] && SCRIPT_DIR="${TE_BASE}/scripts/docs"
    ${SCRIPT_DIR}/doxyrest_compat.py doc/generated/xml || {
        echo "Failed to prepare the Doxygen XML for doxyrest" 1>&2
        return 1
    }

    ${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
    return $?
}

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

if $SPHINX_ONLY; then
    generate_sphinx_only
else
    generate_sphinx_doc
fi
status=$?

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

exit ${status}