Merge "codec2: convert doxygen Android.mk into a script" into main

# =============================================================================

# DOCUMENTATION GENERATION

# =============================================================================

C2_ROOT := $(call my-dir)

C2_DOCS_ROOT := $(OUT_DIR)/target/common/docs/codec2

C2_OUT_TEMP := $(PRODUCT_OUT)/gen/ETC/Codec2-docs_intermediates

C2_DOXY := $(or $(shell command -v doxygen),\

		$(shell command -v /Applications/Doxygen.app/Contents/Resources/doxygen))

.PHONY: check-doxygen

check-doxygen:

ifndef C2_DOXY

	$(error 'doxygen is not available')

endif

$(C2_OUT_TEMP)/doxy-api.config: $(C2_ROOT)/docs/doxygen.config

	# only document include directory, no internal sections

	sed 's/\(^INPUT *=.*\)/\1include\//; \

	s/\(^INTERNAL_DOCS *= *\).*/\1NO/; \

	s/\(^ENABLED_SECTIONS *=.*\)INTERNAL\(.*\).*/\1\2/; \

	s:\(^OUTPUT_DIRECTORY *= \)out:\1'$(OUT_DIR)':;' \

		$(C2_ROOT)/docs/doxygen.config > $@

$(C2_OUT_TEMP)/doxy-internal.config: $(C2_ROOT)/docs/doxygen.config

	sed 's:\(^OUTPUT_DIRECTORY *= \)out\(.*\)api:\1'$(OUT_DIR)'\2internal:;' \

		$(C2_ROOT)/docs/doxygen.config > $@

.PHONY: docs-api

docs-api: $(C2_OUT_TEMP)/doxy-api.config check-doxygen

	echo API docs are building in $(C2_DOCS_ROOT)/api

	rm -rf $(C2_DOCS_ROOT)/api

	mkdir -p $(C2_DOCS_ROOT)/api

	$(C2_DOXY) $(C2_OUT_TEMP)/doxy-api.config

.PHONY: docs-internal

docs-internal: $(C2_OUT_TEMP)/doxy-internal.config check-doxygen

	echo Internal docs are building in $(C2_DOCS_ROOT)/internal

	rm -rf $(C2_DOCS_ROOT)/internal

	mkdir -p $(C2_DOCS_ROOT)/internal

	$(C2_DOXY) $(C2_OUT_TEMP)/doxy-internal.config

.PHONY: docs-all

docs-all: docs-api docs-internal

include $(call all-makefiles-under,$(call my-dir))

# will be relative from the directory where doxygen is started.

# This tag requires that the tag FULL_PATH_NAMES is set to YES.

STRIP_FROM_PATH        = frameworks/av/media/libstagefright/codec2

STRIP_FROM_PATH        = frameworks/av/media/codec2

# The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of the

# path mentioned in the documentation of a class, which tells the reader which

# spaces. See also FILE_PATTERNS and EXTENSION_MAPPING

# Note: If this tag is empty the current directory is searched.

INPUT                  = frameworks/av/media/libstagefright/codec2/

INPUT                  = frameworks/av/media/codec2/

# This tag can be used to specify the character encoding of the source files

# that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses

# need to set EXTENSION_MAPPING for the extension otherwise the files are not

# properly processed by doxygen.

INPUT_FILTER           = frameworks/av/media/libstagefright/codec2/docs/doxyfilter.sh

INPUT_FILTER           = frameworks/av/media/codec2/docs/doxyfilter.sh

# The FILTER_PATTERNS tag can be used to specify filters on a per file pattern

# basis. Doxygen will compare the file name with each pattern and apply the

#!/bin/bash

# Copyright (C) 2024 The Android Open Source Project

#

# Licensed under the Apache License, Version 2.0 (the "License");

# you may not use this file except in compliance with the License.

# You may obtain a copy of the License at

#

#     http://www.apache.org/licenses/LICENSE-2.0

#

# Unless required by applicable law or agreed to in writing, software

# distributed under the License is distributed on an "AS IS" BASIS,

# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

# See the License for the specific language governing permissions and

# limitations under the License.

# =============================================================================

# DOCUMENTATION GENERATION

# =============================================================================

if [ -z "$ANDROID_BUILD_TOP" ]; then

  echo "error: Android build is not set up. Run this command after lunch." >&2

  exit 2

fi

OUT_DIR=$ANDROID_BUILD_TOP/out

# Codec 2.0 source and target paths

C2_ROOT=$(dirname "$0")

C2_DOCS_ROOT=$OUT_DIR/target/common/docs/codec2

C2_OUT_TEMP=$ANDROID_PRODUCT_OUT/gen/ETC/Codec2-docs_intermediates

# Doxygen path

DOXY=$(which doxygen)

DOXY_MAC="/Applications/Doxygen.app/Contents/Resources/doxygen"

if [ -z "$DOXY" -a -x "$DOXY_MAC" ]; then

  DOXY=$DOXY_MAC

fi

if [ -z "$DOXY" ]; then

  echo "error: doxygen is not available" >&2

  exit 2

fi

# Create doxygen config

# ---------------------

gen_doxy() {

  local variant=$1

  local variant_lc=$(echo $variant | tr A-Z a-z)

  mkdir -p $C2_OUT_TEMP

  if [ "$variant_lc" == "api" ]; then

    # only document include directory, no internal sections

    sed 's/\(^INPUT *=.*\)/\1core\/include\//;

      s/\(^INTERNAL_DOCS *= *\).*/\1NO/;

      s/\(^ENABLED_SECTIONS *=.*\)INTERNAL\(.*\).*/\1\2/;

      s:\(^OUTPUT_DIRECTORY *= \)out\(.*\)api:\1'$OUT_DIR'\2'$variant_lc':;' \

      $C2_ROOT/docs/doxygen.config > $C2_OUT_TEMP/doxy-$variant_lc.config

    ls -la $C2_OUT_TEMP/doxy-$variant_lc.config

  else

    sed 's:\(^OUTPUT_DIRECTORY *= \)out\(.*\)api:\1'$OUT_DIR'\2'$variant_lc':;' \

      $C2_ROOT/docs/doxygen.config > $C2_OUT_TEMP/doxy-$variant_lc.config

  fi

  echo $variant docs are building in $C2_DOCS_ROOT/$variant_lc

  rm -rf $C2_DOCS_ROOT/$variant_lc

  mkdir -p $C2_DOCS_ROOT/$variant_lc

  pushd $ANDROID_BUILD_TOP

  $DOXY $C2_OUT_TEMP/doxy-$variant_lc.config

  popd

}

usage() {

  echo "usage: $(basename "$0") [target]"

  echo "  where target can be one of:"

  echo "    all:      build both API and internal docs (default)"

  echo "    api:      build API docs only"

  echo "    internal: build internal docs which include implementation details"

}

TARGET=${1:-all}

case "$TARGET" in

  api) gen_doxy API;;

  internal) gen_doxy Internal;;

  all) gen_doxy API; gen_doxy Internal;;

  -h) usage; exit 0;;

  *) echo "unknown target '$TARGET'" >&2; usage; exit 2;;

esac