Topology2 doxygen documentation infrastructure

tools/topology/topology2/doc/CMakeLists.txt

@@ -0,0 +1,47 @@
+# SPDX-License-Identifier: BSD-3-Clause
+
+cmake_minimum_required(VERSION 3.13)
+
+project(SOF_TOPOLOGY2_DOC NONE)
+
+set(SOF_ROOT_SOURCE_DIRECTORY "${PROJECT_SOURCE_DIR}/..")
+
+set(top_srcdir "${SOF_ROOT_SOURCE_DIRECTORY}")
+set(top_bindir "${PROJECT_BINARY_DIR}")
+
+configure_file(
+	"${PROJECT_SOURCE_DIR}/sof.doxygen.in"
+	"${PROJECT_BINARY_DIR}/sof.doxygen"
+)
+
+file(GLOB_RECURSE topology2_sources "${SOF_ROOT_SOURCE_DIRECTORY}/*.conf")
+file(GLOB_RECURSE extra_sources "${PROJECT_SOURCE_DIR}/extra-contents/*.doxy")
+
+add_custom_command(
+	OUTPUT ${PROJECT_BINARY_DIR}/contents.doxy
+	COMMAND ${PROJECT_SOURCE_DIR}/topology2-generate-contents.sh > ${PROJECT_BINARY_DIR}/contents.doxy
+	DEPENDS ${PROJECT_SOURCE_DIR}/topology2-generate-contents.sh
+	DEPENDS ${topology2_sources}
+	VERBATIM
+)
+
+add_custom_target(doc-contents
+	DEPENDS ${PROJECT_BINARY_DIR}/contents.doxy
+)
+
+add_custom_command(
+	OUTPUT ${PROJECT_BINARY_DIR}/doxygen/html/index.html
+	COMMAND doxygen sof.doxygen
+	DEPENDS ${PROJECT_BINARY_DIR}/sof.doxygen
+	DEPENDS ${PROJECT_SOURCE_DIR}/topology2-filter.py
+	DEPENDS doc-contents
+	DEPENDS ${extra_sources}
+	DEPENDS ${topology2_sources}
+	VERBATIM
+	USES_TERMINAL
+)
+
+add_custom_target(doc ALL
+	DEPENDS ${PROJECT_BINARY_DIR}/doxygen/html/index.html
+	VERBATIM
+)

tools/topology/topology2/doc/README

@@ -0,0 +1,7 @@
+To build the topology2 source documentation do following steps:
+
+cd tools/topology/topology2/doc
+cmake -B build/
+cmake --build build/ -v
+
+After the last command you should find the html documentation under: sof/tools/topology/topology2/doc/build/doxygen/html

tools/topology/topology2/doc/extra-contents/mainpage.doxy

@@ -0,0 +1,32 @@
+/* SPDX-License-Identifier: BSD-3-Clause */
+/* Copyright(c) 2023 Intel Corporation. All rights reserved. */
+/*! \mainpage Sound Open Firmware Topology2
+ *
+ * \section this_document This Document
+ *
+ * This document is generated from SOF topology2 sources and its
+ * purpose is provide examples of how SOF ALSA topologies are built
+ * through instantiating toppology2 classes.
+ *
+ * The documentation is provided using Doxygen package and a Doxygen
+ * filter that translates the topology2 classes into C-structures. The
+ * filter is implemented in python and can be found from
+ * tools/topology/topology2/doc/topology2-filter.py
+ *
+ * The topology2 language syntax is described in detail <a
+ * href="https://thesofproject.github.io/latest/developer_guides/topology2/topology2.html">here</a>.
+ *
+ * \subsection doc_reading Reading the document
+ *
+ * The purpose of the translated C code is not to document actual
+ * topology2 code, but only to provide anchors for Doxygen to form a
+ * network of links through which to navigate the topology sources and
+ * find the pieces of related Doxygen documentation. The filter also
+ * creates separate pages of the original code and add links next to
+ * the pages in the C struct definition and instance documentation.
+ *
+ * The most essential part of the documentation is the documentation of
+ * classes that shown as C structs in this Doxygen documentation.
+ *
+ * \copydoc doc_contents
+ */

tools/topology/topology2/doc/sof.doxygen.in

@@ -0,0 +1,34 @@
+# SPDX-License-Identifier: BSD-3-Clause
+PROJECT_NAME     = "Sound Open Firmware Topology2"
+OUTPUT_DIRECTORY = doxygen
+GENERATE_LATEX   = NO
+GENERATE_RTF	 = NO
+GENERATE_MAN     = NO
+GENERATE_XML	 = YES
+
+CASE_SENSE_NAMES = NO
+INPUT            = @top_srcdir@ \
+		   @top_srcdir@/doc/extra-contents/ \
+		   @top_bindir@/contents.doxy
+
+RECURSIVE	 = YES
+FILE_PATTERNS    = *.conf
+IMAGE_PATH	 =
+QUIET            = YES
+WARN_LOGFILE     = doxygen_warnings.txt
+
+EXTRACT_ALL	 = YES
+EXTRACT_STATIC	 = YES
+WARN_IF_UNDOCUMENTED = NO
+SHOW_INCLUDE_FILES = YES
+JAVADOC_AUTOBRIEF = YES
+INHERIT_DOCS	 = YES
+
+MACRO_EXPANSION  = YES
+EXPAND_ONLY_PREDEF = YES
+OPTIMIZE_OUTPUT_FOR_C = YES
+
+HTML_TIMESTAMP = NO
+
+EXTENSION_MAPPING = conf=C,doxy=C
+FILTER_PATTERNS = *.conf=@top_srcdir@/doc/topology2-filter.py