doc: add requirements into doxygen

#!/usr/bin/env python3

# Copyright (c) 2024 Intel Corp.

# SPDX-License-Identifier: Apache-2.0

import sys

import argparse

import json

HEADER = """

/**

@page Requirements

@tableofcontents

"""

FOOTER = """

*/

"""

def debug(msg):

    print("DEBUG: {}".format(msg))

def parse_nodes(nodes, grouped):

    for n in nodes:

        if n['TYPE'] in ['TEXT'] :

            continue

        elif n['TYPE'] in ['SECTION'] :

            grouped = parse_nodes(n['NODES'], grouped)

        else:

            rid = n.get('UID')

            name = n['TITLE']

            text= n['STATEMENT']

            group = n.get('COMPONENT', None)

            if not group:

                debug("No group for {}".format(rid))

                continue

            if not grouped.get(group, None):

                grouped[group] = []

            grouped[group].append({'rid': rid, 'req': text, 'name': name })

    return grouped

def parse_strictdoc_json(filename):

    grouped = dict()

    with open(filename) as fp:

        data = json.load(fp)

        docs = data.get('DOCUMENTS')

        for d in docs:

            parse_nodes(d['NODES'], grouped)

    return grouped

def write_dox(grouped, output="requirements.dox"):

    with open(output, "w") as req:

        req.write(HEADER)

        counter = 0

        for r in grouped.keys():

            comp = grouped[r]

            counter += 1

            req.write(f"\n@section REQSEC{counter} {r}\n\n")

            for c in comp:

                req.write("@subsection {} {}: {}\n{}\n\n\n".format(c['rid'], c['rid'], c['name'], c['req']))

        req.write(FOOTER)

if __name__ == "__main__":

    parser = argparse.ArgumentParser(description='Create doxygen requirements page', allow_abbrev=False)

    parser.add_argument('--json', help='JSON file to parse')

    parser.add_argument('--output', help='Output file to write to')

    args = parser.parse_args()

    if args.json:

        filename = args.json

        write_dox(parse_strictdoc_json(filename), args.output)

    else:

        sys.exit("no input given")

ALIASES                = "rst=\verbatim embed:rst:leading-asterisk" \

                         endrst=\endverbatim \

                         "kconfig{1}=\htmlonly <code>\1</code> \endhtmlonly \xmlonly <verbatim>embed:rst:inline :kconfig:option:`\1`</verbatim> \endxmlonly" \

                         "req{1}=\ref ZEPH_\1 \"ZEPH-\1\"" \

                         "req{1}=\ref ZEP-\1 \"ZEP-\1\"" \

                         "satisfy{1}=\xrefitem satisfy \"Satisfies requirement\" \"Requirement Implementation\" \1" \

                         "verify{1}=\xrefitem verify \"Verifies requirement\" \"Requirement Verification\" \1" \

                         "kconfig_dep{1}=\attention Available only when the following Kconfig option is enabled: \kconfig{\1}." \

                         @ZEPHYR_BASE@/include/ \

                         @ZEPHYR_BASE@/lib/libc/minimal/include/ \

                         @ZEPHYR_BASE@/subsys/testsuite/include/ \

                         @ZEPHYR_BASE@/subsys/testsuite/ztest/include/

                         @ZEPHYR_BASE@/subsys/testsuite/ztest/include/ \

			 @ZEPHYR_BASE@/tests/kernel/semaphore/ \

              @ZEPHYR_BASE@/tests/kernel/threads/ \

			 @ZEPHYR_BASE@/tests/kernel/mutex/ \

                         @ZEPHYR_BASE@/kernel/sem.c \

			 @ZEPHYR_BASE@/kernel/thread.c \

			 @ZEPHYR_BASE@/kernel/sched.c \

			 @ZEPHYR_BASE@/doc/requirements/requirements.dox

# 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

# ANamespace::AClass, ANamespace::*Test

EXCLUDE_SYMBOLS        = _* \

                         *.__unnamed__ \

                         z_* \

                         Z_*

                         *.__unnamed__

# The EXAMPLE_PATH tag can be used to specify one or more files or directories

# that contain example code fragments that are included (see the \include

# documentation.

# The default value is: NO.

INLINE_SOURCES         = NO

INLINE_SOURCES         = YES

# Setting the STRIP_CODE_COMMENTS tag to YES will instruct Doxygen to hide any

# special comment blocks from generated source code fragments. Normal C, C++ and

                         CONFIG_UART_INTERRUPT_DRIVEN \

                         CONFIG_UART_ASYNC_API \

                         CONFIG_USERSPACE \

			 CONFIG_ZTEST \

                         CONFIG_USE_SWITCH \

			 CONFIG_MULTITHREADING \

                         NET_MGMT_DEFINE_REQUEST_HANDLER(x)= \

                         DEVICE_DEFINE()= \

                         BUILD_ASSERT()= \