rdkcentral / hal-doxygen Goto Github PK

• When doxygen outputs html there's a bug in the render that it's not generated correctly, this is a known bug with doxygen.
• We need to fix the issue in the github code, or check that someone else hasn't fixed it.
• raise a ticket on doxygen github, and submit our change
• In the meantime until the uprevision, we need to keep applying the patch to the code.
• It may be rendered correctly if we followed the same fix that was applied for plantUML.

doxygen/doxygen#9950

Update Doxyfile.cfg:

• INPUT = ../../include
  ../../src
  ./pages *.md
  ../../README.md
  ../../CONTRIBUTING.md
  ../../NOTICE
  ../../COPYING
  ../../LICENCE

Add support for checking the latest version and warning if not on it to be added to the clone script

https://github.com/rdkcentral/hal-doxygen/blob/develop/template/docs/generate_docs.sh

Something akin to the same one for ut-core

# Clone the Unit Test Requirements
[email protected]:rdkcentral/ut-core.git

# This function checks if we're not sitting on the latest revision.
function check_next_revision()
{
    pushd ./ut-core 2&>/dev/null
    # Set default UT_PROJECT_VERSION to next revision
    if [ -v ${UT_PROJECT_VERSION} ]; then
        UT_PROJECT_VERSION=$(git tag | grep ${UT_PROJECT_MAJOR_VERSION} | sort -r | head -n1)
        UT_NEXT_VERSION=$(git tag | sort -r | head -n1)
        echo -e ${YELLOW}ut-core version selected:[${UT_PROJECT_VERSION}]${NC}
        if [ "${UT_NEXT_VERSION}" != "${UT_PROJECT_VERSION}" ]; then
            echo -e ${RED}--- New Version of ut-core released [${UT_NEXT_VERSION}] consider upgrading ---${NC}
        fi
    fi
    popd 2&>/dev/null
}

This sort of thing needs to be removed

# Set default UT_PROJECT_VERSION to master
if [ -z "${UT_PROJECT_VERSION}" ]; then
    UT_PROJECT_VERSION=master
fi

spec needs some example statements to help engineering teams, basic ones to start with.

Move documentation to github pages and set up a template for it.

Doxygen rendering requires below enhancements/fix :

1. The install step in doxygen_install.sh , had to be modified with sudo.
2. It would be good to mention what is the doxygen version expected by generate_docs.sh. If any doxygen version is pre-installed, that’s being used by the script and the generated output will be badly rendered. After running doxygen_install.sh, issue was resolved.
3. Dependent packages were not documented, hence direct script executions were failing. Required packages like flex, bison.

Doxygen

• Upgrade doxygen to support mermaid from .md files into the HTML output, needs to be corrected.
  - It currently works in markdown displayed images, but not in the output for the HTML
• Check the latest version of doxygen, and check the patch level, does it support the above correctly?

new baseline code and clean up

is currently pointing to develop, it should be main to ensure the template consumes official releases not work in progress.

In Doxyfile.cfg, following needs to be changed:

1. USE_MDFILE_AS_MAINPAGE = README.md
2. Add README.md to doxygen param "INPUT"