Restore the "API Documentation" link in sidebar when building with Doxygen >= 1.9.8 (#2135)

Author: lurch

docs/CMakeLists.txt

@@ -55,11 +55,21 @@ if(PICO_BUILD_DOCS)
     set(doxyfile_in ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in)
     set(doxyfile ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile)
 
+    if(DOXYGEN_VERSION VERSION_GREATER_EQUAL "1.9.8")
+        # see https://github.com/doxygen/doxygen/issues/10562
+        set(DOXY_API_DOCS_TAB_TYPE "topics")
+    else()
+        set(DOXY_API_DOCS_TAB_TYPE "modules")
+    endif()
+    set(doxylayout_in ${CMAKE_CURRENT_SOURCE_DIR}/DoxygenLayout.xml.in)
+    set(doxylayout ${CMAKE_CURRENT_BINARY_DIR}/DoxygenLayout.xml)
+
     if (PICO_PLATFORM STREQUAL "rp2040")
         set(PICO_DOXYGEN_TAG "(RP2040)")
     elseif (PICO_PLATFORM STREQUAL "rp2350-arm-s" OR PICO_PLATFORM STREQUAL "rp2350-riscv")
         set(PICO_DOXYGEN_TAG "(RP2350)")
     endif()
+    configure_file(${doxylayout_in} ${doxylayout} @ONLY)
     configure_file(${doxyfile_in} ${doxyfile} @ONLY)
 
     add_custom_target(docs

docs/Doxyfile.in

@@ -17,7 +17,7 @@ FILE_PATTERNS          = *.h \
                          *.md
 
 USE_MDFILE_AS_MAINPAGE = @PROJECT_SOURCE_DIR@/docs/mainpage.md
-LAYOUT_FILE = @PROJECT_SOURCE_DIR@/docs/DoxygenLayout.xml
+LAYOUT_FILE = @PROJECT_BINARY_DIR@/docs/DoxygenLayout.xml
 HTML_FOOTER = @PROJECT_SOURCE_DIR@/docs/footer.html
 HTML_HEADER = @PROJECT_SOURCE_DIR@/docs/header.html
 
@@ -65,4 +65,4 @@ PREDEFINED             = __not_in_flash_func(x)= \
                          DOXYGEN_GENERATION= \
                          @DOXY_PREDEFINED@
 
-ENABLED_SECTIONS       = @DOXY_ENABLED_SECTIONS@
+ENABLED_SECTIONS       = @DOXY_ENABLED_SECTIONS@

docs/DoxygenLayout.xml renamed to docs/DoxygenLayout.xml.in

@@ -3,7 +3,7 @@
   <!-- Navigation index tabs for HTML output -->
   <navindex>
     <tab type="mainpage" visible="yes" title="Introduction"></tab>
-    <tab type="modules" visible="yes" title="API Documentation" intro="These are the libraries supplied in the Raspberry Pi Pico SDK"/>
+    <tab type="@DOXY_API_DOCS_TAB_TYPE@" visible="yes" title="API Documentation" intro="These are the libraries supplied in the Raspberry Pi Pico SDK"/>
     <tab type="user" url="@ref examples_page" visible="yes" title="Examples" intro="Links to SDK examples"/>
     <tab type="usergroup" url="@ref weblinks_page" visible="yes" title="Additional Documentation" intro="Links to datasheets and documentation">
       <tab type="user" url="https://rptl.io/pico-datasheet" visible="yes" title="Raspberry Pi Pico Datasheet" intro=""/>